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Foreword 


(This Foreword is not a part of IEEE Std 1003.1-1988, IEEE Standard Portable Operating System 
Interface for Computer Environments.) 


The purpose of this standard is to define a standard operating system inter- 
face and environment based on the UNIX* Operating System documentation to 
support application portability at the source level. This is intended for systems 
implementors and applications software developers. 

In its present form, the standard focuses primarily on the C Language inter- 
face to the operating system. 

IEEE Std 1003.1-1988 is the first of a group of proposed standards known col- 
loquially, and collectively, as POSIX}. The other POSIX standards are described 
in Appendix A. 


Organization of the Standard. The standard is divided into four parts: 
(1) Statement of scope (Chapter 1) 
(2) Definitions and global concepts (Chapter 2) 
(3) The various interface facilities (Chapters 3 through 9) 
(4) Data interchange format (Chapter 10) 
This foreword and the appendices are not considered part of the standard. 
Most of the sections describe a single service interface. The C Language bind- 
ing for the service interface is given in the subsection labeled Synopsis. The 
Description subsection provides a specification of the operation performed by 
the service interface. Some examples may be provided to illustrate the inter- 
faces described. In most cases there are also Returns and Errors subsections 
specifying return values and possible error conditions. References are used to 
direct the reader to other related sections. Additional material to complement 
sections in the standard may be found in Rationale and Notes, Appendix B. 
This appendix provides historical perspectives into the technical choices made 
by the 1003.1 Working Group. It also provides information to emphasize conse- 
quences of the interfaces described in the corresponding section of the standard. 
In publishing this standard, both the IEEE and the 1003.1 Working Group 
simply intend to provide a yardstick against which various operating system 
implementations can be measured for conformance. It is not the intent of either 
the IEEE or the 1003.1 Working Group to measure or rate any products, to 
reward or sanction any vendors of products for conformance or lack of confor- 
mance to this standard, or to attempt to enforce this standard by these or any 
other means. The responsibility for determining the degree of conformance or 
lack thereof with this standard rests solely with the individual who is evaluat- 
ing the product claiming to be in conformance with the standard. (See Verifi- 
cation Testing §A.2.4 for additional information on this subject.) 


* UNIX is a registered trademark of AT&T. 
+ POSIX is pronounced pahz-icks, similar to positive. 


Base Documents. The various interface facilities described herein are based 
on the 1984 /usr/group Standard derived and published by the /usr/group 
Standards Committee, Santa Clara, California. The 1984 /usr/group Standard 
and subsequent work of the 1003.1 Working Group is largely based on UNIX 
Seventh Edition, UNIX System III, UNIX System V, 4.2BSD, and 4.3BSD docu- 
mentation, but wherever possible, compatibility with other systems derived 
from the UNIX operating system, or systems compatible with that system, has 
been maintained. 

The IEEE is grateful to both AT&T and /usr/group for permission to use their 
materials. 


Typographic Conventions. This standard uses the following typographic 
conventions: 
(1) The italic font is used for the initial appearances of defined terms; cross 
references to defined terms within the sections Terminology §2.1, Confor- 
mance §2.2, and General Terms §2.3; symbolic parameters that are gen- 
erally substituted with real values by the application; C language data types 
and function names (except in function Synopsis sections); and global exter- 
nal variable names. 
(2) The bold font is used for C language data types and function names 
within function Synopsis sections; references to other sections or chapters 
within the standard. A bold word in all capital letters, such as 


PATH 


represents an environment variable, as described in Environment 
Description §2.7. 

(3) The constant -width font is used to illustrate examples of system input 
or output where exact usage is depicted. It is also used for references to util- 
ity names defined in IEEE Std 1003.2 or found in historical implementations. 
(4) Error number values returned by many functions are represented as: 


[ERRNO] 


See Error Numbers 82.5. 
(5) Symbolic constants or limits defined in certain headers are represented 
as: 


{LIMIT} 


See Numerical Limits §2.9 and Symbolic Constants §2.10. 

In some cases tabular information is presented “inline;” in others it is 
presented in a separately-labeled Table. This arrangement was employed 
purely for ease of typesetting and there is no normative difference between 
these two cases. 

The conventions listed here are for ease of reading only. Editorial incon- 
sistencies in the use of typography are unintentional and have no normative 
meaning in this standard. 


Extensions and Supplements to this Standard. Activities to extend this 
standard to address additional requirements are in progress and similar efforts 
can be anticipated in the future. This is an outline of how these extensions will 
be incorporated, and also how users of this document can keep track of that 
status. 


Extensions are approved as Supplements to this document, following the IEEE 
Standards Procedures. 

Approved Supplements are published separately and distributed with orders 
from the IEEE for this document until the full document is reprinted and such 
supplements are incorporated in their proper positions. 

If you have any question about the completeness of your version, you may con- 
tact the IEEE Computer Society [(202) 371-0101] or the IEEE Standards Office 
[(212) 705-7960] to determine what supplements have been published. 

Supplements are numbered in the same format as the main document, and 
with unique positions as either subsections or main sections. A supplement may 
include new subsections in various sections of the main document as well as 
new main sections. Supplements may include new sections in already approved 
supplements. However, the overall numbering shall be unique so that two sup- 
plements do not use the same numbers unless one replaces the other. 

Supplements may contain either required functions or optional facilities. 
Supplements may add additional conformance requirements (see Confor- 
mance §2.2) defining new classes of conforming systems or applications. 

It is undesirable, but perhaps unavoidable, for supplements to change the 
functionality of the already defined facilities. 

Supplements are not used to provide a general update of the standard. This is 
done through the review procedure as specified by the IEEE. 

The following areas are under active consideration at this time, or are 
expected to become active in the near future: 

(1) Shell and Utility facilities — P1003.2 (see Shell and Utilities §A.2.3); 

(2) Verification Testing — P1003.3 (see Verification Testing §A.2.4); 

(3) Realtime facilities — P1003.4 (see Realtime Extensions §A.2.5); 

(4) Ada* Language bindings — P1003.5 (see Ada Language Bindings 
§A.2.6): 

(5) Secure/Trusted System considerations — P1003.6 (see Trusted System 
Extensions §A.2.7); 

(6) Language-independent service descriptions (this will be the subject of a 
future supplement to this standard); 

(7) FORTRAN Language bindings; 

(8) Network interface facilities (see Networking Standards §A.2.10); 
(9)System Administration (see System Administration Extensions 
§A.2.9); 

(10) An overall guide to POSIX-based or related Open Systems standards — 
P1003.0 (see Open System Guidelines §A.2.8). 

If you have interest in participating in the working groups addressing these 
issues, please send your name, address, and phone number to the: 


Ry 


Ada is a registered trademark of the U.S. Government — Ada Joint Program Office. 


Secretary, IEEE Standards Board 

Institute of Electrical and Electronics Engineers, Inc. 
345 East 47th Street 

New York, NY 10017 

USA 


and ask to have this forwarded to the chairperson of the appropriate 1003 Work- 
ing Group. 


IEEE Std 1003.1-1988 was prepared by the 1003.1 Working Group, sponsored 
by the Technical Committee on Operating Systems of the IEEE Computer 
Society. At the time this standard was approved, the membership of the 1003.1 
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Portable Operating System Interface 
for Computer Environments 


1. Scope 


This standard defines a standard operating system interface and environment 
to support application portability at the source code level. It is intended to be 
used by both application developers and system implementors. 

Initially, the focus of this standard will be to provide standardized services via 
a C language interface. Future revisions are expected to contain bindings for 
other programming languages as well as for the C language. This will be accom- 
plished by breaking the standard into two parts—a section defining core 
requirements independent of any programming language, and a section com- 
posed of programming language bindings. 

The core requirements section will define a set of required services common to 
any programming language that can be reasonably expected to form a language 
binding to this standard. These services will be described in terms of functional 
requirements and will not define programming language-dependent interfaces. 
Language bindings will consist of two major parts. One will contain the pro- 
gramming language’s standardized interface for accessing the core services 
defined in the programming language-independent core requirements section of 
the standard. The other will contain a standardized interface for language- 
specific services. Any implementation claiming conformance to IEEE Std 
1003.1-1988 with any language binding shall comply with both sections of the 
language binding. ; 

This standard is comprised of four major components: 

(1) Terminology, concepts, and definitions and specifications that govern 
structures, headers, environment variables, and related requirements. 

(2) Definitions for system service interfaces and subroutines. 

(3) Language-specific system services for the C programming language. 

(4) Interface issues, including portability, error handling, and error recovery. 
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The following areas are outside of the scope of this standard: 
(1) User interface (shell) and associated commands. 
(2) Networking protocols and system call interfaces to those protocols. 
(3) Graphics interfaces. 
(4) Database management system interfaces. 
(5) Record I/O considerations. 
(6) Object or binary code portability. 
(7) System configuration and resource availability. 
(8) The behavior of system services on systems supporting concurrency 
within a single process. 
(See Appendix A for information about ongoing efforts in some of these areas.) 
This standard describes the external characteristics and facilities that are of 
importance to applications developers, rather than the internal construction 
techniques employed to achieve these capabilities. Special emphasis is placed 
on those functions and facilities that are needed in a wide variety of commercial 
applications. 
This standard has been defined exclusively at the source code level. The 
objective is that a Strictly Conforming POSIX Application source program can be 
translated to execute on a conforming implementation. 
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2. Definitions and General Requirements 


2.1 Terminology. The following terms are used in this standard: 


implementation-defined. A value or behavior is implementation-defined if 
the implementation defines and documents the requirements for correct pro- 
gram construct and correct data. 


may. With respect to implementations, the word may is to be interpreted as an 
optional feature that is not required in this standard but can be provided. With 
respect to Strictly Conforming POSIX Applications, the word may means that 
the optional feature shall not be used. 


shall. In this standard, the word shall is to be interpreted as a requirement on 
the implementation or on Strictly Conforming POSIX Applications, where 
appropriate. 


should. With respect to implementations, the word should is to be interpreted 
as an implementation recommendation, but not a requirement. With respect to 
applications, the word should is to be interpreted as recommended program- 
ming practice for applications and a requirement for Strictly Conforming POSIX 
Applications. 


supported. Certain functionality in this standard is optional, but the inter- 
faces to that functionality are always required. Ifthe functionality is supported , 
the interfaces work as specified by this standard (except that they do not return 
the error condition indicated for the not-supported case). If the functionality is 
not supported, the interface shall always return the indication specified for this 
situation. 


undefined. A value or behavior is undefined if the standard imposes no porta- 
bility requirements on applications for erroneous program construct, erroneous 
data, or use of an indeterminate value. Implementations (or other standards) 
may specify the result of using that value or causing that behavior. An applica- 
tion using such behaviors is using extensions, as defined in Conforming POSIX 
Application Using Extensions §2.2.2.3. 
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unspecified. A value or behavior is unspecified if the standard imposes no por- 
tability requirements on applications for a correct program construct or correct 
data. Implementations (or other standards) may specify the result of using that 
value or causing that behavior. An application requiring a specific behavior, 
rather than tolerating any behavior when using that functionality, is using 
extensions, as defined in Conforming POSIX Application Using Extensions 
§2°2.2.3. 


2.2 Conformance. 


2.2.1 Implementation Conformance. 
2.2.1.1 Requirements. A conforming implementation shall meet all of 

the following criteria: 

(1) The system shall support all required interfaces defined within this stan- 

dard. These interfaces shall support the functional behavior described 

herein. 

(2) The system may provide additional functions or facilities not required by 

this standard. Nonstandard extensions should be identified as such in the 

system documentation. Nonstandard extensions, when used, may change 

the behavior of functions or facilities defined by this standard. In such cases, 

the system documentation shall define an environment in which an applica- 

tion can be run with the behavior specified by the standard. In no case shall 

such an environment require modification of a Strictly Conforming POSIX 

Application. 

2.2.1.2 Documentation. A document with the following information 

shall be available for an implementation claiming conformance to IEEE Std 
1003.1-1988. This document shall have the same structure as this standard, 
with the information presented in the appropriately numbered sections. The 
document shall not contain information about extended facilities or capabilities 
outside the scope of this standard. 

The document shall contain a conformance statement that indicates the full 
name, number, and date of the standard that applies. The conformance section 
may also list software standards approved by ISO or any ISO member body that 
are available for use by a Conforming POSIX Application. Applicable charac- 
teristics where documentation is required by one of these standards, or by stan- 
dards of government bodies, may also be included. 

The document shall describe the contents of the <limits.h> and <unistd.h> 
headers, stating values, the conditions under which those values may change, 
and the limits of such variations, if any. 

The document shall describe the behavior of the implementation for all 
implementation-defined features identified in this standard. The document is 
not required to describe those features identified as undefined or unspecified. 

The document should specify the behavior of the implementation in those sec- 
tions of this standard where it is stated that implementations may vary. 
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2.2.1.3 Conforming Implementation Options. The following symbolic 
constants, described in the sections indicated, reflect implementation options for 
this standard that could warrant requirement by Conforming POSIX Applica- 
tions, or in specifications of conforming systems, or both: 
{NGROUPS_MAX} 
Multiple groups option (in Run-Time Increasable Values §2.9.3) 
{ POSIX_JOB_CONTROL} 
Job control option (in Compile-Time Symbolic Constants 
§2.10.3) 
{ POSIX_CHOWN_RESTRICTED} 
Administrative/security option (in Execution-Time Symbolic 
Constants §2.10.4) 

The remaining symbolic constants in Compile-Time Symbolic Constants 
§2.10.3 and Execution-Time Symbolic Constants §2.10.4 are useful for test- 
ing purposes, and as a guide to applications on the types of behaviors they need 
to be able to accommodate. They do not reflect sufficient functional difference to 
warrant requirement by Conforming POSIX Applications or in distinguishing 
between conforming implementations. 

In the cases where omission of an option would cause functions described by 
this standard to not be defined, an implementation shall provide a function that 
is callable with the syntax defined in the standard, even though in an instance 
of the implementation the function may always do nothing but return an error. 


2.2.2 Application Conformance. All applications claiming conformance 
to this standard shall use only Language-Dependent Services for the C 
Programming Language §2.2.3, and shall fall within one of the following 
categories: 

2.2.2.1 Strictly Conforming POSIX Application. A Strictly Conform- 
ing POSIX Application is an application that requires only the facilities 
described in this standard and the applicable language standards. Such an 
application shall accept any behavior described in this standard as 
implementation-defined, and for symbolic constants, shall accept any value in 
the range permitted by this standard. Such applications are permitted to adapt 
to the availability of facilities whose availability is indicated by the constants in 
<limits.h> §2.9 and <unistd.h> §2.10. 
2.2.2.2 Conforming POSIX Application. 

2.2.2.2.1 ISO Conforming POSIX Application. An [SO Conforming 
POSIX Application is an application that uses only the facilities described in this 
standard and approved Conforming Language bindings for any ISO standard. 
Such an application shall include a statement of conformance that documents 
all options and limit dependencies, and all other ISO standards used. 

2.2.2.2.2 <National Body> Conforming POSIX Application. A 
<National Body> Conforming POSIX Application differs from an ISO Conform- 
ing POSIX Application in that it also may use specific standards of a single ISO 
member body referred to here as “<National Body>.” Such an application shall 
include a statement of conformance that documents all options and limit depen- 
dencies, and all other <National Body> standards used. 
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2.2.2.3 Conforming POSIX Application Using Extensions. A Con- 
forming POSIX Application Using Extensions is an application that differs from 
a Conforming POSIX Application only in that it uses non-standard facilities 
which are consistent with this standard. Such an application shall fully docu- 
ment its requirements for these extended facilities, in addition to the documen- 
tation required of a Conforming POSIX Application. A Conforming POSIX Appli- 
cation Using Extensions shall be either an ISO Conforming POSIX Application 
Using Extensions or a <National Body> Conforming POSIX Application Using 
Extensions (see sections §2.2.2.2.1 and §2.2.2.2.2). 


2.2.3 Language-Dependent Services for the C Programming 
Language. When the C Standard (ANSI/X3.159-198x Programming Language 
C Standard) is ratified, parts of it will be referenced to describe requirements 
also mandated by IEEE Std 1003.1-1988. The sections of the C Standard refer- 
enced to describe requirements for this standard are specified in Chapter 8. 
Chapter 8 also sets forth additions and amplifications to the referenced sections 
of the C Standard. Any implementation claiming conformance to IEEE Std 
1003.1-1988 with the C Language Binding shall provide the facilities referenced 
in Chapter 8, along with any additions and amplifications Chapter 8 requires. 

Although IEEE Std 1003.1-1988 references parts of the C Standard to describe 
some of its own requirements, conformance to the C Standard is unnecessary for 
conformance to IEEE Std 1003.1-1988. Any C Language implementation provid- 
ing the facilities stipulated in Chapter 8 may claim conformance—however, it 
shall clearly state that its C language does not conform to the C Standard. 

2.2.3.1 Types of Conformance. Implementations claiming conformance 
to IEEE Std 1003.1-1988 with the C Language Binding shall claim one of two 
types of conformance—conformance to IEEE Std 1003.1-1988, C Language Bind- 
ing (C Standard Language-Dependent System Support), or to IEEE Std 1003.1- 
1988, C Language Binding (Common Usage C Language-Dependent System 
Support). 

2.2.3.2 C Standard Language-Dependent System Support. Imple- 
mentors shall meet the requirements of Chapter 8 using for reference the 
C Standard. Implementors shall clearly document the version of the 
C Standard referenced in fulfilling the requirements of Chapter 8. 

Until the C Standard is ratified, implementors shall reference the draft of 
that document dated 13 May 1988 (X3J11/88-002). Implementors seeking to 
claim conformance using the draft C Standard shall claim conformance to IEEE 
Std 1003.1-1988, C Language Binding (C Standard Language-Dependent Sys- 
tem Support). Those implementors shall clearly document that the draft ver- 
sion of the C Standard referred to in implementing Chapter 8 was the draft 
dated 13 May 1988. Implementations using the draft C Standard prior to the 
formal ratification of that standard should change their implementations to 
reflect changes to the C Standard once it is ratified. 
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2.2.3.3 Common Usage C Language-Dependent System Support. 
Implementors, instead of referencing the C Standard, shall provide the routines 
and support required in Chapter 8 using common usage as guidance. Imple- 
mentors shall meet all the requirements of Chapter 8 except where references 
are made to the C Standard. In places where the C Standard is referenced, 
implementors shall provide equivalent support in a manner consistent with 
common usage of the C programming language. Implementors shall document 
any differences between the interface provided and the interface that would 
have been provided had the C Standard been referenced instead of common 
usage. Implementors shall clearly document the version of the C Standard 
referenced in documenting interface differences and should issue updates on 
differences for all new versions of the C Standard. 

Until the C Standard is ratified, implementors claiming conformance to IEEE 
Std 1003.1-1988, C Language Binding (Common Usage Language-Dependent 
System Support) shall reference the draft C Standard dated 13 May 1988 when 
documenting interface differences between their implementation of Chapter 8 
and implementations of Chapter 8 based on the C Standard. 

Where a function has been introduced by the C Standard, and thus there is no 
common usage referent for it, if the function is implemented, it shall be imple- 
mented as described in the C Standard. If the function is not implemented, it 
shall be documented as a difference from the C Standard as required above. 


2.2.4 Other C Language Related Specifications. The following rules 
apply to the usage of C language library functions; each of the statements in 
this section applies to the detailed function descriptions in Chapters 3 through 
9, unless explicitly stated otherwise: 

(1) If an argument to a function has an invalid value (such as a value outside 
the domain of the function, or a pointer outside the address space of the pro- 
gram, or a NULL pointer when that is not explicitly permitted), the behavior 
is undefined. 

(2) Any function may also be implemented as a macro in a header. Applica- 
tions should use #undef to remove any macro definition and ensure that an 
actual function is referenced. Applications should also use #undef prior to 
declaring any function in this standard. 

(3) Any invocation of a library function that is implemented as a macro shall 
expand to code that evaluates each of its arguments only once, fully pro- 
tected by parentheses where necessary, so it is generally safe to use arbi- 
trary expressions as arguments. ; 

(4) Provided that a library function can be declared without reference to any 
type defined in a header, it is also permissible to declare the function, either 
explicitly or implicitly, and use it without including its associated header. 

(5) If a function that accepts a variable number of arguments is not declared 
(explicitly, or by including its associated header), the behavior is undefined. 
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2.3 General Terms. The following are definitions of terms peculiar to this 
standard: 


absolute pathname. See pathname resolution $2.4. 
access mode. A form of access permitted to a file. 
address space. The memory locations that can be referenced by a process. 


appropriate privileges. An implementation-defined means of associating 
privileges with a process with regard to the function calls and function call 
options defined in this standard that need special privileges. There may be zero 
or more such means. 


background process group. Any process group that is a member of a session 
which has established a connection with a controlling terminal that is not in the 
foreground process group. 


block special file. A file that refers to a device. A block special file is nor- 
mally distinguished from a character special file by providing access to the dev- 
ice in a manner such that the hardware characteristics of the device are not visi- 
ble. 


C Standard. The abbreviated name for the ANSI/X3.159-198x Programming 
Language C Standard. 


character. A sequence of one or more bytes representing a single graphic sym- 
bol. 


character special file. A file that refers to a device. One specific type of char- 
acter special file is a terminal device file, whose access is defined in General 
Terminal Interface §7.1. Other character special files have no structure 
defined by this standard and their use is implementation-defined. 


child process. See process. 


clock tick. The number of intervals per second, defined by {CLK_TCK}, used to 
express the value in type clock_t. 


controlling process. The session leader that established the connection to the 
controlling terminal. Should the terminal subsequently cease to be a control- 
ling terminal for this session, the session leader shall cease to be the controlling 
process. 


controlling terminal. A terminal that is associated with a session. Each ses- 
sion may have at most one controlling terminal associated with it and a control- 
ling terminal is associated with exactly one session. Certain input sequences 
from the controlling terminal (see General Terminal Interface §7.1) cause 
signals to be sent to all processes in the process group associated with the con- 
trolling terminal. 
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current working directory. See working directory. 


device. A computer peripheral or an object that appears to the application as 
such. 


directory. A file that contains directory entries. No two directory entries in the 
same directory shall have the same name. 


directory entry (or link). An object that associates a filename with a file. 
Several directory entries can associate names with the same file. 


dot. The filename consisting of a single dot character (.). See pathname reso- 
lution §2.4. 


dot-dot. The filename consisting solely of two dot characters (..). See path- 
name resolution §2.4. 


effective group ID. An attribute of a process that is used in determining vari- 
ous permissions, including file access permissions §2.4. See group ID. This 
value is subject to change during the process lifetime, as described in setgid() 
§4.2.2 and exec §3.1.2. 


effective user ID. An attribute of a process that is used in determining various 
permissions, including file access permissions §2.4. See user ID. This value 
is subject to change during the process lifetime, as described in setuid() §4.2.2 
and exec §3.1.2. 


empty directory. A directory that contains, at most, directory entries for dot 
and dot-dot. 


empty string (or null string). A character array whose first element is a null 
character. 


Epoch. The time 0 hours, 0 minutes, 0 seconds, January 1, 1970 Coordinated 
Universal Time. See seconds since the Epoch. 


feature test macro. A #defined symbol used to determine whether a partic- 
ular set of features will be included from a header. See Symbols From The C 
Standard §2.8.1. 


FIFO special file (or FIFO). A type of file. Data written to such a file is read 
on a first-in-first-out basis. Other characteristics of FIFOs are described under 
open() §5.3.1, read() §6.4.1, write() §6.4.2, and lseek() §6.5.3. 


file. An object that can be written to, or read from, or both. A file has certain 
attributes, including access permissions and type. File types include regular 
file, character special file, block special file, FIFO special file, and directory. 
Other types of files may be defined by the implementation. 


file description. See open file description. 
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file descriptor. A per-process unique, non-negative integer used to identify an 
open file for the purpose of file access. 


file group class. A process is in the file group class of a file if the process is not 
in the file owner class and if the effective group ID or one of the supplementary 
group IDs of the process matches the group ID associated with the file. Other 
members of the class may be implementation-defined. 


file mode. An object containing the file permission bits and other characteris- 
tics of a file, as described in <sys/stat.h> §5.6.1. 


filename. A name consisting of 1 to {NAME_MAX} bytes used to name a file. 
The characters composing the name may be selected from the set of all charac- 
ter values excluding the slash character and the null character. The filenames 
dot and dot-dot have special meaning; see pathname resolution §2.4. A 
filename is sometimes referred to as a pathname component. 


file offset. The byte position in the file where the next I/O operation begins. 
Each open file description associated with a regular file, block special file, or 
directory has a file offset. A character special file that does not refer to a termi- 
nal device may have a file offset. There is no file offset specified for a pipe or 
FIFO. 


file other class. A process is in the file other class of a file if the process is not 
in the file owner class or file group class. 


file owner class. A process is in the file owner class of a file if the effective user 
ID of the process matches the user ID of the file. 


file permission bits. Information about a file that is used, along with other 
information, to determine if a process has read, write, or execute/search permis- 
sion to a file. The bits are divided into three parts: owner, group, and other. 
Each part is used with the corresponding file class of processes. These bits are 
contained in the file mode, as described in <sys/stat.h> §5.6.1. The detailed 
usage of the file permission bits in access decisions is described in file access 
permissions §2.4. 


file serial number. A per-file system unique identifier for a file. File serial 
numbers are unique throughout a file system. 


file system. A collection of files and certain of their attributes. It provides a 
name space for file serial numbers referring to those files. 


foreground process group. Each session that has established a connection 
with a controlling terminal has exactly one process group of the session as the 
foreground process group of that controlling terminal. The foreground process 
group has certain privileges when accessing its controlling terminal that are 
denied to background process groups. See Terminal Access Control §7.1.1.4. 
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foreground process group ID. The process group ID of the foreground pro- 
cess group. 


group ID. Each system user is a member of at least one group. A group is 
identified by a group ID, a non-negative integer that can be contained in an 
object of type gid_t. When the identity of a group is associated with a process, a 
group ID value is referred to as a real group ID, an effective group ID, one of the 
(optional) supplementary group IDs, or an (optional) saved set-group-ID. 


job control. A facility that allows users to selectively stop (suspend) the execu- 
tion of processes and continue (resume) their execution at a later point. The 
user typically employs this facility via the interactive interface jointly supplied 
by the terminal I/O driver and a command interpreter. Conforming implemen- 
tations may optionally support job control facilities; the presence of this option 
is indicated to the application at compile time or run time by the definition of 
the {_POSIX_JOB_CONTROL} symbol; see Symbolic Constants §2.10). 


link. See directory entry. 
link count. The number of directory entries that refer to a particular file. 


mode. A collection of attributes that specifies a file’s type and its access per- 
. missions. (See file access permissions §2.4). 


null string. See empty string. 
open file. A file that is currently associated with a file descriptor. 


open file description. A record of how a process or group of processes are 
accessing a file. Each file descriptor shall refer to exactly one open file descrip- 
tion, but an open file description may be referred to by more than one file 
descriptor. A file offset, file status (see Table 6-5 in Data Definitions for File 
Control Operations §6.5.1), and file access modes (Table 6-6) are attributes of 
an open file description . 


orphaned process group. A process group in which the parent of every 
member is either itself a member of the group or is not a member of the group’s 
session . 


parent directory. When discussing a directory, the directory containing the 
directory entry for the directory under discussion. When discussing other types 
of files, a directory containing a directory entry for the file under discussion. 
This concept does not apply to dot and dot-dot. 


parent process. See process. 


parent process ID. A new process is created by a currently active process. 
The parent process ID of a process is the process ID of its creator, for the lifetime 
of the creator. After the creator’s lifetime has ended, the parent process ID is 
the process ID of an implementation-defined system process. 
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path prefix. A pathname, with an optional ending slash, that refers to a direc- 
tory. 


pathname. A string that is used to identify a file. It consists of, at most, 
{PATH_MAX} bytes, including the terminating null character. It has an optional 
beginning slash, followed by zero or more filenames separated by slashes. If the 
pathname refers to a directory, it may also have one or more trailing slashes. 
Multiple successive slashes are considered the same as one slash. A pathname 
that begins with two successive slashes may be interpreted in an 
implementation-defined manner, although more than two leading slashes shall 
be treated as a single slash. The interpretation of the pathname is described 
under pathname resolution $2.4. 


pathname component. See filename. 


pipe. An object accessed by one of the pair of file descriptors created by the 
pipe() function. Once created, the file descriptors can be used to manipulate it 
and it behaves identically to a FIFO special file when accessed in this way. It 
has no name in the file hierarchy $2.4. 


portable filename character set. For a filename to be portable across con- 
forming implementations of IEEE Std 1003.1-1988, it shall consist only of the 
following characters: 


K lL MN © P QO RoSely U VW oes 
k 1 mn Op ¢Qd © SE UY weave 


GHIJ 
aD. Gert eG i155 
OR Ss 4 oom) Od 


The last three characters are the period, underscore, and hyphen characters, 
respectively. The hyphen shall not be used as the first character of a portable 
filename. Upper- and lowercase letters shall retain their unique identities 
between conforming implementations. In the case of a portable pathname, the 
slash character may also be used. 


privilege. See appropriate privileges. 


process. An address space and single thread of control that executes within 
that address space, and its required system resources. A process is created by 
another process issuing the fork() function. The process that issues fork() is 
known as the parent process, and the new process created by the fork() as the 
child process. 


process group. Each process in the system is a member of a process group that 
is identified by a process group ID. This grouping permits the signaling of 
related processes. A newly-created process joins the process group of its creator. 


process group ID. Each process group in the system is uniquely identified dur- 
ing its lifetime by a positive integer that can be contained in a pid_t called a pro- 
cess group ID. A process group ID may not be reused by the system until the pro- 
cess group lifetime ends. 
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process group leader. A process whose process ID is the same as its process 
group ID. 


process group lifetime. A period of time that begins when a process group is 
created and ends when the last remaining process in the group leaves the group, 
either due to process termination or calling the setsid() or setpgid() functions. 


process ID. Each process in the system is uniquely identified during its lifetime 
by a positive integer that can be contained in a pid_t called a process ID. A pro- 
cess ID may not be reused by the system until the process lifetime ends. In addi- 
tion, if there exists a process group whose process group ID is equal to that pro- 
cess ID, the process ID may not be reused by the system until the process group 
lifetime ends. A process that is not a system process shall not have a process ID 
of 1. 


process lifetime. After a process is created with a fork() function, it is con- 
sidered active. Its thread of control and address space exist until it terminates. 
It then enters an inactive state where certain resources may be returned to the 
system, although some resources, such as the process ID, are still in use. When 
another process executes a wait() or waitpid() function for an inactive process, 
the remaining resources are returned to the system. The last resource to be 
returned to the system is the process ID. At this time, the lifetime of the process 
ends. 


read-only file system. A file system that has implementation-defined charac- 
teristics restricting modifications. 


real group ID. The attribute of a process that, at the time of process creation, 
identifies the group of the user who created the process. See group ID. This 
value is subject to change during the process lifetime, as described in setgid() 
§4.2.2. 


real user ID. The attribute of a process that, at the time of process creation, 
identifies the user who created the process. See user ID. This value is subject 
to change during the process lifetime, as described in setuid() §4.2.2. 


regular file. A file that is a randomly accessible sequence of bytes, with no 
further structure imposed by the system. 


relative pathname. See pathname resolution §2.4. 


root directory. A directory, associated with a process, that is used in path- 
name resolution §2.4 for pathnames that begin with a slash. 


saved set-group-ID. When the saved set-user-ID option is implemented, an 
attribute of a process that allows some flexibility in the assignment of the effec- 
tive group ID attribute, as described in setgid() §4.2.2, and exec §3.1.2. 


saved set-user-ID. When the saved set-user-ID option is implemented, an 
attribute of a process that allows some flexibility in the assignment of the effec- 
tive user ID attribute, as described in setuid() §4.2.2, and exec §3.1.2. 
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seconds since the Epoch. A value to be interpreted as the number of seconds 
between a specified time and the Epoch. A Coordinated Universal Time name 
(specified in terms of seconds (tm_sec), minutes (fm_min), hours (tm_hour), 
days since January 1 of the year (tm_yday), and calendar year minus 1900 
(tm_year)) is related to a time represented as seconds since the Epoch according 
to the expression below. 

If year < 1970 or the value is negative, the relationship is undefined. If year = 
1970 and the value is non-negative, the value is related to a Coordinated 
Universal Time name according to the expression: 


tm_sec + tm_min*60 + tm_hour*3 600 + tm_yday*86 400 + 
(tm_year—70)*31 536 000 + ((tm_year—69)/4)*86 400 


session. Each process group is a member of a session. A process is considered 
to be a member of the session of which its process group is a member. A newly- 
created process joins the session of its creator. A process can alter its session 
membership (see setsid() §4.3.2). Implementations which support setpgid() 
§4.3.3 can have multiple process groups in the same session. 


session leader. A process that has created a session (see setsid() §4.3.2). 


session lifetime. The period between when a session is created and the end of 
the lifetime of all the process groups which remain as members of the session. 


signal. A mechanism by which a process may be notified of, or affected by, an 
event occurring in the system. Examples of such events include hardware 
exceptions and specific actions by processes. The term signal is also used to 
refer to the event itself. 


slash. The literal character “/”. This character is also known as solidus in ISO 
8859/1. 


supplementary group ID. A process has up to {NGROUPS_MAX} supplemen- 
tary group IDs used in determining file access permissions, in addition to the 
effective group ID. The supplementary group IDs of a process are set to the sup- 
plementary group IDs of the parent process when the process is created. 
Whether a process’s effective group ID is included in or omitted from its list of 
supplementary group IDs is unspecified. 


system. An implementation of this standard. 


system process. An object, other than a process executing an application, that 
is defined by the system and has a process ID. 


terminal (or terminal device). A character special file that obeys the specifi- 
cations of the General Terminal Interface §7.1. 


user ID. Each system user is identified by a non-negative integer known as a 
user ID that can be contained in an object of type uid_t. When the identity of a 
user is associated with a process, a user ID value is referred to as a real user ID, 
an effective user ID, or an (optional) saved set-user-ID. 
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working directory (o7 current working directory). A directory, associated 
with a process, that is used in pathname resolution §2.4 for pathnames that 
do not begin with a slash. 


2.4 General Concepts. 


extended security controls. The access control (see file access permissions) 
and privilege (see appropriate privileges §2.3) mechanisms have been 
defined to allow implementation-defined extended security controls. These per- 
mit an implementation to provide security mechanisms to implement different 
security policies than are described in this standard. These mechanisms shall 
not alter or override the defined semantics of any of the functions in this stan- 
dard. 


file access permissions. The standard file access control mechanism uses the 
file permission bits, as described below. These bits are set at file creation by 
open() §5.3.1, creat() §5.3.2, mkdir() §5.4.1, and mA&fifo() §5.4.2, and are 
changed by chmod() 85.6.4. These bits are read by stat() or fstat() §5.6.2. 

Implementations may provide additional or alternate file access control 
mechanisms, or both. An additional access control mechanism shall only 
further restrict the access permissions defined by the file permission bits. An 
alternate access control mechanism shall: 

(1) Specify file permission bits for the file owner class, file group class, and 
file other class of the file, corresponding to the access permissions, to be 
returned by stat() or fstat(). 

(2) Be enabled only by explicit user action, on a per-file basis by the file 
owner or a user with the appropriate privilege. 

(3) Be disabled for a file after the file permission bits are changed for that 
file with chmod(). The disabling of the alternate mechanism need not dis- 
able any additional mechanisms defined by an implementation. 

Whenever a process requests file access permission for read, write, or 
execute/search, if no additional mechanism denies access, access is determined 
as follows: 

(1) If a process has the appropriate privilege: 
(a) If read, write, or directory search permission is requested, access is 
granted. 
(b) If execute permission is requested, access is granted if execute permis- 
sion is granted to at least one user by the file permission bits or by an 
alternate access control mechanism; otherwise access is denied. 

(2) Otherwise: 
(a) The file permission bits of a file contain read, write, and 
execute/search permissions for the file owner class, file group class, and 
file other class. 
(b) Access is granted if an alternate access control mechanism is not 
enabled and the requested access permission bit is set for the class to 
which the process belongs, or if an alternate access control mechanism is 
enabled and it allows the requested access; otherwise access is denied. 
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file hierarchy. Files in the system are organized in a hierarchical structure in 
which all of the non-terminal nodes are directories and all of the terminal nodes 
are any other type of file. Because multiple directory entries may refer to the 
same file, the hierarchy is properly described as a directed graph. 


filename portability. Filenames should be constructed from the portable 
filename character set because the use of other characters can be confusing or 
ambiguous in certain contexts. 


file times update. Each file has three associated time values that are updated 
when file data has been accessed, file data has been modified, or file status has 
been changed, respectively. These values are returned in the file characteristics 
structure, as described in <sys/stat.h> $5.6.1. 

For each function in this standard that reads or writes file data or changes 
the file status, the appropriate time-related fields are noted as marked for 
update. An implementation may update fields that are marked for update 
immediately, or may update such fields periodically. When the fields are 
updated they are set to the current time and the update marks are cleared. All 
fields that are marked for update shall be updated when the file is no longer 
open by any process, or when a stat() $5.6.2 or fstat() is performed on the file. 
Other times at which updates are done are unspecified. Updates are not done 
for files on read-only file systems. 


pathname resolution. Pathname resolution is performed for a process to 
resolve a pathname to a particular file in a file hierarchy. There may be multi- 
ple pathnames that resolve to the same file. 

Each filename in the pathname is located in the directory specified by its 
predecessor (for example, in the pathname fragment “a/b”, file “b” is located in 
directory “a”). Pathname resolution fails if this cannot be accomplished. If the 
pathname begins with a slash, the predecessor of the first filename in the path- 
name is taken to be the root directory of the process (such pathnames are 
referred to as absolute pathnames). If the pathname does not begin with a 
slash, the predecessor of the first filename of the pathname is taken to be the 
current working directory of the process (such pathnames are referred to as 
relative pathnames). 

The interpretation of a pathname component is dependent on the values of 
{NAME_MAX} and {_POSIX_NO_TRUNC} associated with the path prefix of that 
component. If any pathname component is longer than {NAME_MAX}, and 
{_POSIX_NO_TRUNC} is in effect for the path prefix of that component (see path- 
conf() §5.7.1), the implementation shall consider this an error condition. Other- 
wise, the implementation shall use the first {NAME_MAX} bytes of the pathname 
component. 

The special filename, dot, refers to the directory specified by its predecessor. 
The special filename, dot-dot, refers to the parent directory of its predecessor 
directory. As a special case, in the root directory, dot-dot may refer to the root 
directory itself. 

A pathname consisting of a single slash resolves to the root directory of the 
process. A null pathname is invalid. 
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2.56 Error Numbers. Most functions provide an error number in the external 
variable errno, which is defined as: 


extern int errno; 


The value of this variable shall be defined only after a call to a function for 
which it is explicitly stated to be set, and until it is changed by the next function 
call. The variable errno should only be examined when it is indicated to be valid 
by a function’s return value. No function defined in this standard sets errno to 
zero to indicate an error. 

If more than one error occurs in processing a function call, this standard does 
not define in what order the errors are detected; therefore, any one of the possi- 
ble errors may be returned. 

Implementations may support additional errors not included in this list, may 
generate errors included in this list under circumstances other than those 
described here, or may contain extensions or limitations that prevent some 
errors from occurring. The Errors subsection in each function description 
specifies which error conditions shall be required and which may be 
implementation-defined. Implementations shall not generate an error number 
different from the ones described here for error conditions described in this 
standard. 

The following symbolic names identify the possible error numbers, in the con- 
text of functions specifically defined in this standard; these general descriptions 
are more precisely defined in the Errors sections of functions that return them. 
Only these symbolic names should be used in programs, since the actual value 
of the error number is implementation-defined. All values listed in this section 
shall be unique. The implementation-defined values for these names shall be 
found in the header <errno.h>. 

[E2BIG] Arg list too long 
The sum of the number of bytes used by the new process 
image’s argument list and environment list was greater than 
the system-imposed limit of {[ARG_MAX} bytes. 

[EACCES] Permission denied 
An attempt was made to access a file in a way forbidden by its 
file access permissions. 

[EAGAIN] Resource temporarily unavailable 
This is a temporary condition and later calls to the same routine 
may complete normally. 

[EBADF] Bad file descriptor 
A file descriptor argument was out of range, referred to no open 
file, or a read (write) request was made to a file that was only 
open for writing (reading). 

[EBUSY] Resource busy 
An attempt was made to use a system resource that was not 
available at the time because it was being used by a process ina 
manner that would have conflicted with the request being made 
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[ECHILD] 


[EDEADLK] 


[EDOM] 


[EEXIST] 


[EFAULT] 


[EFBIG] 


[EINTR] 


[EINVAL] 


[EIO] 


[EISDIR] 


[EMFILE] 


[EMLINK] 


[ENAMETOOLONG] _ Filename too long 


38 


IEEE STANDARD PORTABLE OPERATING SYSTEM 


by this process. 

No child processes 

A wait() or waitpid() function was executed by a process that 
had no existing or unwaited-for child processes. 

Resource deadlock avoided 

An attempt was made to lock a system resource that would 
have resulted in a deadlock situation. 

Domain error 

Defined in the C Standard; an input argument was outside the 
defined domain of the mathematical function. 

File exists 

An existing file was specified in an inappropriate context, for 
instance, as the new link name in a Jink() function. 

Bad address 

The system detected an invalid address in attempting to use an 
argument of a call. The reliable detection of this error is 
implementation-defined; however, implementations that do 
detect this condition shall use this value. 

File too large 

The size of a file would exceed an implementation-defined max- 
imum file size. 

Interrupted function call 

An asynchronous signal (such as SIGINT or SIGQUIT; see the 
description of header <signal.h> §3.3.1) was caught by the pro- 
cess during the execution of an interruptible function. If the 
signal handler performs a normal return, the interrupted func- 
tion call may return this error condition. 

Invalid argument 

Some invalid argument was supplied. (For example, specifying 
an undefined signal to a signal() or Rill() function). 
Input/output error 

Some physical input or output error occurred. This error may 
be reported on a subsequent operation on the same file descrip- 
tor. Any other error-causing operation on the same file descrip- 
tor may cause the [EIO] error indication to be lost. 

Is a directory 

An attempt was made to open a directory with write mode 
specified. 

Too many open files 

An attempt was made to open more than the maximum number 
of {OPEN_MAX} file descriptors allowed in this process. 

Too many links 

An attempt was made to have the link count of a single file 
exceed {LINK_MAX}. 

The size of a pathname string exceeded {PATH_MAX}, or a path- 
name component was longer than {NAME_MAX} and 


Definitions and General Requirements 


IEEE 


INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


[ENFILE] 


[ENODEV] 


[ENOENT] 


[ENOEXEC] 


[ENOLCK] 


[ENOMEM] 


[ENOSPC] 


[ENOSYS] 


[ENOTDIR] 


{_POSIX_NO_TRUNC} was in effect for that file. 

Too many open files in system 

Too many files are currently open in the system. The system 
reached its predefined limit for simultaneously open files and 
temporarily could not accept requests to open another one. 

No such device 

An attempt was made to apply an inappropriate function to a 
device; for example, trying to read a write-only device such as a 
printer. 

No such file or directory 

A component of a specified pathname did not exist, or the path- 
name was an empty string. 

Exec format error 

A request was made to execute a file that, although it had the 
appropriate permissions, was not in the format required by the 
implementation for executable files. 

No locks available 

A system-imposed limit on the number of simultaneous file and 
record locks was reached and no more were available at that 
time. 

Not enough space 

The new process image required more memory than was 
allowed by the hardware or by system-imposed memory 
management constraints. 

No space left on device 

During a write() function on a regular file, or when extending a 
directory, there was no free space left on the device. 

Function not implemented 

An attempt was made to use a function that is not available in 
this implementation. 

Not a directory 

A component of the specified pathname existed, but it was not a 
directory, when a directory was expected. 


[ENOTEMPTY] Directory not empty 


[ENOTTY] 


[ENXIO] 


[EPERM] 


A directory with entries other than dot and dot-dot was sup- 
plied when an empty directory was expected. 

Inappropriate I/O control operation 

A control function was attempted for a file or special file for 
which the operation was inappropriate. 

No such device or address 

Input or output on a special file referred to a device that did not 
exist, or made a request beyond the limits of the device. This 
error may also occur when, for example, a tape drive is not on- 
line or no disk pack is loaded on a drive. 

Operation not permitted 

An attempt was made to perform an operation limited to 
processes with appropriate privileges or to the owner of a file or 
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other resource. 

[EPIPE] Broken pipe 
A write was attempted on a pipe or FIFO for which there was no 
process to read the data. 

[ERANGE] Result too large 
Defined in the C Standard; the result of the function was too 
large to fit in the available space. 

[EROFS] Read-only file system 
An attempt was made to modify a file or directory on a file sys- 
tem that was read-only at that time. 

[ESPIPE] Invalid seek 
An lseek() function was issued on a pipe or FIFO. 

[ESRCH] No such process 
No process could be found corresponding to that specified by the 
given process ID. 

[EXDEV] Improper link 
A link to a file on another file system was attempted. 


2.6 Primitive System Data Types. Some data types used by the various 
system functions are not defined as part of this standard, but are defined by the 
implementation. These types are then defined in the header <sys/types.h>, 
which contains definitions for at least the types shown in Table 2-1. 


Table 2-1. Primitive System Data Types 


Defined Type a eserpon ee 


dev_t Used for device numbers. 

gid_t Used for group IDs. 

ino_t Used for file serial numbers. 

mode_t Used for some file attributes, for example file 
type, file access permissions. 

nlink_t Used for link counts. 

off_t Used for file sizes. 

pid_t Used for process IDs and process group IDs. 

uid_t Used for user IDs. 


All of the types listed in Table 2-1 shall be arithmetic types; pid_t shall be a 
signed arithmetic type. 

Additional implementation-defined type definitions may be given in this 
header. These definitions shall have names ending with _t. Such symbols do 
not require feature test macros to be visible when <sys/types.h> is included. 


2.7 Environment Description. An array of strings called the environment is 
made available when a process begins. This array is pointed to by the external 
variable environ , which is defined as: 


extern char **environ; 
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These strings have the form “name=value”; names shall not contain the charac- 
ter =. There is no meaning associated with the order of the strings in the 
environment. If more than one string in a process’s environment has the same 
name, the consequences are undefined. The following names may be defined 
and have the indicated meaning if they are defined: 


HOME The name of the user’s initial working directory, from the 
user database (see the description of the header <pwd.h> 
§9.2.2). 

LANG The name of the predefined setting for locale. 

LC_COLLATE The name of the locale for collation information. 

LC_CTYPE The name of the locale for character classification. 


LC_MONETARY The name of the locale containing monetary-related 
numeric editing information. 

LC_NUMERIC The name of the locale containing numeric editing (i.e., 
radix character) information. 


LC_TIME The name of the locale for date/time formatting informa- 
tion. 
LOGNAME The name of the user’s login account, corresponding to the 


login name in the user database (see the description of the 
header <pwd.h>). The value shall be composed of charac- 
ters from the portable filename character set §2.3. 
PATH The sequence of path prefixes that certain functions apply 
in searching for an executable file known only by a 
filename (a pathname that does not contain a slash). The 
prefixes are separated by a colon (:). When a non-zero- 
length prefix is applied to this filename, a slash is inserted 
between the prefix and the filename. A zero-length prefix 
is a special prefix that indicates the current working direc- 
tory. It appears as two adjacent colons (“::”), as an initial 
colon preceding the rest of the list, or as a trailing colon 
following the rest of the list. The list is searched from 
beginning to end until an executable program by the speci- 
fied name is found. If the pathname being sought contains 
a slash, the search through the path prefixes is not per- 
formed. 
TERM The terminal type for which output is to be prepared. This 
information is used by commands and application pro- 
grams wishing to exploit special capabilities specific to a 
terminal. 
TZ Time zone information. The format of this string is 
defined in Extensions to Time Functions §8.1.1. 
Environment variable names used or created by an application should consist 
solely of characters from the portable filename character set. Other characters 
may be permitted by an implementation; applications shall tolerate the presence 
of such names. Upper- and lowercase letters retain their unique identities and 
are not folded together. System-defined environment variable names should 
begin with a capital letter or underscore, and be composed of only capital letters, 
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underscores, and numbers. 

The values that the environment variables may be assigned are not restricted 
except that they are considered to end with a null byte and the total space used 
to store the environment and the arguments to the process is limited to 
{ARG_MAX} bytes. 

Other name=value pairs may be placed in the environment by manipulating 
the environ variable or by using enup arguments when creating a process (see 
exec §3.1.2). 


2.8 C Language Definitions. 


2.8.1 Symbols From The C Standard. Certain terms and symbols used in 
this standard are considered to be defined by the C programming language. The 
following terms are defined in the C Standard: CLK_TCK, NULL, byte, character 
array, clock_t, header, null character, string, time_t. 

The term NULL pointer in this standard is equivalent to the term null pointer 
used in the C Standard. The symbol NULL shall be declared in <unistd.h>, 
with the same value as required by the C Standard, in addition to the several 
locations already required by the C Standard. 

Additionally, the reservation of symbols that begin with an underscore 
applies: 

(1) All external identifiers that begin with an underscore are reserved. 

(2) All other identifiers that begin with an underscore and either an upper- 
case letter or another underscore are reserved. 
(3) If the program defines an external identifier with the same name as a 
reserved external identifier, even in a semantically equivalent form, the 
behavior is undefined. 

Certain other namespaces are reserved by the C Standard. These reserva- 
tions apply to this standard as well. Additionally, the C Standard requires that 
it be possible to include a header more than once, and that a symbol may be 
defined in more than one header. This requirement is also made of headers for 
this standard. 


2.8.2 POSIX Symbols. Certain symbols in this standard are defined in 
headers. Some of those headers could also define other symbols than those 
defined by this standard, potentially conflicting with symbols used by the appli- 
cation. Also, this standard defines symbols which are not permitted by other 
standards to appear in those headers without some control on the visibility of 
those symbols. 

Symbols called feature test macros are used to control the visibility of symbols 
that might be included in a header. Implementations, future versions of this 
standard, and other standards may define additional feature test macros. 
Feature test macros shall be defined in the compilation of an application before 
a #include of any header where a symbol should be visible to some, but not all, 
applications. If the definition of the macro does not precede the #include, the 
result is undefined. 

Feature test macros shall begin with the underscore character (_ ). 
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Implementations may add members to a structure or union without control- 
ling the visibility of those members with a feature test macro. 
The following feature test macro is defined: 


Name Description 
_POSIX_SOURCE The program expects that the symbols 


defined by this standard will be provided 
by the environment. Where extensions are 
permitted in a header, but no explicit con- 
straint on the form of the name is provided 
by this standard, the extensions shall not 
be made visible by this feature test macro. 


The exact meaning of feature test macros depends on the type of C language 
support chosen: 

2.8.2.1 C Standard Language-Dependent Support. If there are no 
feature test macros present in a program, only the set of symbols defined by the 
C Standard shall be present. For each feature test macro present, only the sym- 
bols specified by that feature test macro plus those of the C Standard shall be 
defined when a header is included. 

2.8.2.2 Common Usage-Dependent Support. Ifthe feature test macro 
_POSIX_SOURCE is not defined in a program, the set of symbols defined in each 
header that are beyond the requirements of this standard is implementation- 
defined. 

If -POSIX_SOURCE is defined before any header is included, no symbols other 
than those from the C Standard and those made visible by feature test macros 
defined for the program (including _POSIX_SOURCE) will be visible. 

If .POSIX_SOURCE is not defined before any header is included, the behavior 
is undefined. 


2.8.3 Headers and Function Prototypes. Implementations claiming 
C Standard Language-Dependent Support shall declare function prototypes for 
all functions. 

Implementations claiming Common Usage C Language-Dependent Support 
shall declare the result type for all functions not returning a “plain” int. 

These function prototypes (if required) shall appear in the headers listed 
below. If a function is not listed below, it shall have its prototype appear in 
<unistd.h>, which is presumed to be #include-ed whenever any function 
declared in it is used, whether or not it is mentioned in the Synopsis section for 
that function. Functions also described in the C Standard (see Language- 
Specific Services for the C Programming Language §8) shall have their 
prototypes appear in the headers defined for them in the C Standard. The 
requirements about visibility of symbols in POSIX Symbols §2.8.2 shall be 
honored. 

<dirent.h> opendir() §5.1.2, readdir() §5.1.2, rewinddir() §5.1.2, 
closedir () §5.1.2. 
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<fentl.h> open() §5.3.1, creat() §5.3.2, fentl() §6.5.2. 
<grp.h> getgrgid() §9.2.1, getgrnam() §9.2.1. 
<pwd.h> getpwuid() §9.2.2, getpwnam() §9.2.2. 
<setjmp.h> sigsetjmp() §8.3.1, siglongjmp () 88.3.1. 
<signal.h> kill() §3.3.2, sigemptyset () §3.3.3, sigfillset() §3.3.3, 


sigaddset() §3.3.3, sigdelset () §3.3.3, sigismember() 
§3.3.3, sigaction() §3.3.4, sigprocmask() §3.3.5, sigpend- 
ing () §3.3.6, sigsuspend () §3.3.7. 

<stdio.h> fileno() §8.2.1, fdopen() §8.2.2. 

<sys/stat.h> umask() §5.3.3, mkdir() §5.4.1, mkfifoQ §5.4.2, statQ 
§5.6.2, fstat() §5.6.2, chmod() §5.6.4. 

<sys/times.h> times() 84.5.2. 

<sys/utsname.h> uname() §4.4.1. 

<sys/wait.h> wait() §3.2.1, waitpid() §3.2.1. 

<termios.h> cfgetospeed () §7.1.2.7, cfsetospeed() §7.1.2.7, cfgetispeed() 
§7.1.2.7, cfsetispeed() §7.1.2.7, tegetatir() §7.2.1, 
tcsetattr() §7.2.1, tesendbreak() §7.2.2, tedrain() §7.2.2, 
tcflush() §7.2.2, teflow() §7.2.2. 

<time.h> time() §4.5.1, tzset() §8.3.2. 

<utime.h> utime() §5.6.6. 


2.9 Numerical Limits. The following subsections list magnitude limitations 
imposed by a specific implementation. The braces notation, {LIMIT}, is used in 
the standard to indicate these values, but the braces are not part of the name. 


2.9.1 C Language Limits. Certain limits used in this standard are con- 
sidered to be defined in the C programming language. The following limits are 
defined in the C Standard (for information on that standard, see the section on 
C Language Standard §A.2.2): {CHAR_BIT}, {CHAR_MAX}, {CHAR_MIN}, 
{INT_MAX}, {INT_MIN}, {LONG_MAX}, {LONG_MIN}, {MB_LEN_MAX}, 
{SCHAR_MAX}, {SCHAR_MIN}, {SHRT_MAX}, {SHRT_MIN}, {UCHAR_MAX}, 
{UINT_MAX}, {ULONG_MAX}, {USHRT_MAX}. 


2.9.2 Minimum Values. The symbols in Table 2-2 shall be defined in 
<limits.h> with the values shown. These are symbolic names for the most res- 
trictive value for certain features on a system conforming to this standard. 
Related symbols are defined elsewhere in this standard which reflect the actual 
implementation and which may not be as restrictive. A conforming implemen- 
tation shall provide values at least this large. A portable application shall not 
require a larger value for correct operation. 


2.9.3 Run-Time Increasable Values. The magnitude limitations in Table 
2-3 shall be fixed by specific implementations. 

A Strictly Conforming POSIX Application shall assume that the value 
supplied by <limits.h> in a specific implementation is the minimum that per- 
tains whenever the Strictly Conforming POSIX Application is run under 
that implementation. A specific instance of a specific implementation may 
increase the value relative to that supplied by <limits.h> for that implementa- 
tion. The actual value supported by a specific instance shall be provided by the 
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Table 2-2. Minimum Values 


Name Description Value 
{_POSIX_ARG_MAX} The length of the arguments for oneof 4096 


the exec functions in bytes, including 
environment data. 


{_POSIX_CHILD_MAX} The number of simultaneous processes 6 
per real user ID. 

{_POSIX_LINK_MAX} The value of a file’s link count. 8 

{_POSIX_MAX_CANON} The number of bytes in a terminal 255 
canonical input queue. 

{ POSIX_MAX_INPUT} The number of bytes for which space 255 
will be available in a terminal input 
queue. 

{ POSIX_NAME_MAX} ; The number of bytes in a filename. 14 

{_POSIX_NGROUPS_MAX} The number of simultaneous supple- 0 
mentary group IDs per process. 

{_POSIX_OPEN_MAX} The number of files that one process 16 
can have open at one time. 

{_POSIX_PATH_MAX} The number of bytes in a pathname. 255 

{_POSIX_PIPE_BUF} The number of bytes that can be writ- biz 


ten atomically when writing to a pipe. 


Table 2-3. Run-Time Increasable Values 


Name Description Minimum Value 
{NGROUPS_MAX} Maximum number of { POSIX NGROUPS_MAX} 


simultaneous supplemen- 
tary group IDs per process. 


sysconf() §4.8.1 function. 


2.9.4 Run-Time Invariant Values (Possibly Indeterminate). A defini- 
tion of one of the values in Table 2-4 shall be omitted from the <limits.h> on 
specific implementations where the corresponding value is equal to or greater 
than the stated minimum, but is indeterminate. 

This might depend on the amount of available memory space on a specific 
instance of a specific implementation. The actual value supported by a specific 
instance shall be provided by the sysconf() §4.8.1 function. 


2.9.5 Pathname Variable Values. The values in Table 2-5 may be con- 
stants within an implementation, or may vary from one pathname to another. 
For example, file systems or directories may have different characteristics. 
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Table 2-4. Run-Time Invariant Values (Possibly Indeterminate) 


Name 
{ARG_ MAX} 


{CHILD_MAX} 


{OPEN_MAX} 


Name 
{LINK_MAX} 


{MAX_CANON} 


{MAX INPUT} 


{NAME_MAX} 


{PATH_MAX} 


{PIPE_BUF} 


Description 


Maximum length of arguments for 
the exec functions in bytes, includ- 
ing environment data. 

Maximum number of simultaneous 
processes per real user ID. 
Maximum number of files that one 
process can have open at any given 
time. 


Minimum Value 


{_POSIX_ARG_MAX} 


{_POSIX_CHILD_MAX} 


{_ POSIX_OPEN_MAX} 


Table 2-5. Pathname Variable Values 


Maximum value of a file’s link 
count. 


Maximum number of bytes in a ter- 
minal canonical input line. (See 
Canonical Mode Input Process- 
ing §7.1.1.6.) 


Minimum number of bytes for 
which space will be available in a 
terminal input queue; therefore, 
the maximum number of bytes a 
portable application may require to 
be typed as input before reading 
them. 

Maximum number of bytes in a file 
name (not a string length; count 
excludes a terminating null). 
Maximum number of bytes in a 
pathname (not a string length; 
count excludes a terminating null). 
Maximum number of bytes that 
can be written atomically when 
writing to a pipe. 


Description —_—_ 


Minimum Value 


{_POSIX_LINK_MAX} 


{_POSIX_MAX_CANON} 


{ POSIX_MAX_INPUT} 


{ POSIX_NAME_MAX} 


{_POSIX_PATH_MAX} 


{_POSIX_PIPE_BUF} 


A definition of one of the values from Table 2-5 shall be omitted from the 
<limits.h> on specific implementations where the corresponding value is equal 
to or greater than the stated minimum, but where the value can vary depending 
on the file to which it is applied. The actual value supported for a specific path- 


name shall be provided by the pathconf() §5.7.1 function. 
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2.10 Symbolic Constants. A conforming implementation shall have the 
header <unistd.h>. This header defines the symbolic constants and structures 
referenced elsewhere in the standard. The constants defined by this header are 
shown below. The actual values of the constants are implementation-defined. 


2.10.1 Symbolic Constants for the access() Function. The constants 
used by the access() function are shown in Table 2-6. 


Table 2-6. Symbolic Constants for the access() Function 


Constant Description 


R_OK Test for read permission. 

W_OK Test for write permission. 

X_OK Test for execute or search permission. 
F_OK Test for existence of file. 


The constants F_OK, R_OK, W_OK, and X_OK and the expressions 
R_OK | W_OK 
(where the | represents the bitwise inclusive OR operator), 
R_OK | X_OK 
and 
R_OK | W_OK | X_OK 
shall all have distinct values. 


2.10.2 Symbolic Constant for the /seek() Function. The constants used 
by the /seek() function are shown in Table 2-7. 


Table 2-7. Symbolic Constants for the /seek() Function 


Constant Description 
SEEK_SET Set file offset to offset. 
SEEK_CUR _ Set file offset to current plus offset. 
SEEK_END Set file offset to EOF plus offset. 


2.10.3 Compile-Time Symbolic Constants for Portability Specifica- 
tions. The constants in Table 2-8 may be used by the application, at compile 
time, to determine which optional facilities are present and what actions shall 
be taken by the implementation. 

Although a Strictly Conforming POSIX Application can rely on the values com- 
piled from the <unistd.h> header to afford it portability on all instances of an 
implementation, it may choose to interrogate a value at run-time to take advan- 
tage of the current configuration. See sysconf() §4.8.1. 
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Table 2-8. Compile-Time Symbolic Constants 


Name Description 
{_POSIX_JOB_CONTROL} _ If this symbol is defined, it indicates that the imple- 
mentation supports job control. 


{ POSIX_SAVED_IDS} If defined, each process has a saved set-user-ID and a 
saved set-group-ID. 
{ POSIX_VERSION} The integer value 198808L. This value will change 


with each published version or revision of this stan- 
dard to indicate the (4-digit) year and (2-digit) month 
that the standard was approved by the IEEE Stan- 
dards Board. 


2.10.4 Execution-Time Symbolic Constants for Portability Specifica- 
tions. The constants in Table 2-9 may be used by the application, at execution 
time, to determine which optional facilities are present and what actions shall 
be taken by the implementation in some circumstances described by this stan- 
dard as implementation-defined. 

If any of the constants in Table 2-9 are not defined in the header <unistd.h>, 
the value varies depending on the file to which it is applied. See pathconf() 
Sone 

If any of the constants in Table 2-9 are defined to have value —1 in the header 
<unistd.h>, the implementation shall not provide the option on any file; if any 
are defined to have a value other than -1 in the header <unistd.h>, the imple- 
mentation shall provide the option on all applicable files. 


Table 2-9. Execution-Time Symbolic Constants 


Nae Descente 

{ POSIX_CHOWN_RESTRICTED} The use of the chown() §5.6.5 function is 
restricted to a process with appropriate 
privileges, and to changing the group ID of 
a file only to the effective group ID of the 
process or to one of its supplementary 


group IDs. 
{_POSIX_NO_TRUNC} Pathname components longer than 
{NAME_MAX} generate an error. 
{_POSIX_VDISABLE} Terminal special characters defined in 


<termios.h> §7.1.2 can be disabled using 
this character value, if it is defined. See 
tcgetattr() and tcsetatir() §7.2.1. 


All of the constants in Table 2-9, whether defined in <unistd.h> or not, may 
be queried with respect to a specific file using the pathconf() or fpathconf() func- 
tions. 
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3. Process Primitives 


The functions described in this chapter perform the most primitive operating 
system services dealing with processes, interprocess signals, and timers. All 
attributes of a process that are specified in this standard shall remain 
unchanged by a process primitive unless the description of that process primi- 
tive states explicitly that the attribute is changed. 


3.1 Process Creation and Execution. 


3.1.1 Process Creation. 
Function: forkQ) 
3.1.1.1 Synopsis. 


#include <sys/types.h> 
pid_t fork () 


3.1.1.2 Description. The fork() function creates a new process. The new 
process (child process) shall be an exact copy of the calling process (parent pro- 
cess) except for the following: 
(1) The child process has a unique process ID. The child process ID also does 
not match any active process group ID. 
(2) The child process has a different parent process ID (which is the process 
ID of the parent process). 
(3) The child process has its own copy of the parent’s file descriptors. Each of 
the child’s file descriptors refers to the same open file description with the 
corresponding file descriptor of the parent. 
(4) The child process has its own copy of the parent’s open directory streams 
(see Directory Operations §5.1.2). Each open directory stream in the child 
process may share directory stream positioning with the corresponding direc- 
tory stream of the parent. 
(5) The child process’s values of tms_utime, tms_stime, tms_cutime, and 
tms_cstime are set to zero (see times() §4.5.2). 
(6) File locks previously set by the parent are not inherited by the child. (See 
fentl() §6.5.2.) 
(7) Pending alarms are cleared for the child process. (See alarm() §3.4.1.) 
(8) The set of signals pending for the child process is initialized to the empty 
set. (See <signal.h> §3.3.1.) 
All other process characteristics defined by this standard shall be the same in 
the parent and the child processes. The inheritance of process characteristics 
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not defined by this standard is implementation-defined. 

3.1.1.3 Returns. Upon successful completion, fork() shall return to the 
child process a value of zero and shall return to the parent process the process 
ID of the child process, and both processes shall continue to execute from the 
fork( function. Otherwise, a value of —1 shall be returned to the parent process, 
no child process shall be created, and errno shall be set to indicate the error. 

3.1.1.4 Errors. If any of the following conditions occur, the fork() func- 
tion shall return —1 and set errno to the corresponding value: 

[EAGAIN] The system lacked the necessary resources to create another 
process, or the system-imposed limit on the total number of 
processes under execution by a single user would be exceeded. 

For each of the following conditions, if the condition is detected, the fork() 
function shall return —1 and set errno to the corresponding value: 

[ENOMEM] The process requires more space than the system is able to sup- 
ply. 

3.1.1.5 References. alarm() §3.4.1, exec §3.1.2, fentlO §6.5.2, Rill 
§3.3.2, times() §4.5.2, wait §3.2.1. 


3.1.2 Execute a File. 
Functions: execl(), execuv(), execle(), execuve(), execlp(), execup () 
3.1.2.1 Synopsis. 


int execl (path, arg0, argl,..., argn, (char *) 0) 
char «path, «arg0, *argl,..., *argn; 


int execv (path, argv) 
char «path, «argu[]; 


int execle (path, arg0, argl,..., argn, (char *) 0, enup) 
char «path, «arg0, *argl,..., xargn, *enup[ }; 


int execve (path, argu, enup); 
char *path, *argu[ ], «enup[ }; 


int execlp (file, arg0, arg1,..., argn, (char *) 0) 
char «file, «arg0, «argl,..., *argn; 


int execvp (file, argu) 
char *file, argu[ ]; 


extern char **environ; 


3.1.2.2 Description. The exec family of functions shall replace the 
current process image with a new process image. The new image is constructed 
from a regular, executable file called the new process image file. There shall be 
no return from a successful exec, because the calling process image is overlaid 
by the new process image. 
When a C program is executed as a result of this call, it shall be entered as a 
C language function call as follows: 
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int main (argc, argu) 
int argc; 
char **argu; 


where argc is the argument count and argv is an array of character pointers to 
the arguments themselves. In addition, the following variable: 


extern char **environ; 


is initialized as a pointer to an array of character pointers to the environment 
strings. The argu and environ arrays are each terminated by a NULL pointer. 
The NULL pointer terminating the argv array is not counted in argc. 

The arguments specified by a program with one of the exec functions shall be 
passed on to the new process image in the corresponding main() arguments. 

The argument path points to a pathname that identifies the new process 
image file. 

The argument file is used to construct a pathname that identifies the new pro- 
cess image file. If the file argument does not contain a slash character, the path 
prefix for this file is obtained by a search of the directories passed as the 
environment variable PATH (see Environment Description §2.7). If this 
environment variable is not present, the results of the search are 
implementation-defined. 

The arguments arg0, argl, ..., argn are pointers to null-terminated charac- 
ter strings. These strings constitute the argument list available to the new pro- 
cess image. The list is terminated by a NULL pointer. The argument arg0 
should point to a filename that is associated with the process being started by 
one of the exec functions. 

The argument argu is an array of character pointers to null-terminated 
strings. The last member of this array shall be a NULL pointer. These strings 
constitute the argument list available to the new process image. The value in 
argu[0] should point to a filename that is associated with the process being 
started by one of the exec functions. 

The argument enup is an array of character pointers to null-terminated 
strings. These strings constitute the environment for the new process image. 
The enup array is terminated by a NULL pointer. 

For those forms not containing an enup pointer (execl(), execu(), execlp(), and 
execup()) the environment for the new process image is taken from the external 
variable environ in the calling process. 

The number of bytes available for the new process’s combined argument and 
environment lists is {ARG_MAX}. The implementation shall specify in the sys- 
tem documentation (see Documentation §2.2.1.2) whether any combination of 
null terminators, pointers, or alignment bytes are included in this total. 

File descriptors open in the calling process image remain open in the new pro- 
cess image, except for those whose close-on-exec flag FD_CLOEXEC is set (see 
fentl() §6.5.2, <fentl.h> §6.5.1). For those file descriptors that remain open, all 
attributes of the open file description, including file locks (see fentl() §6.5.2), 
remain unchanged by this function call. 
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Signals set to the default action (SIG_DFL) in the calling process image shall 
be set to the default action in the new process image. Signals set to be ignored 
(SIG_IGN) by the calling process image shall be set to be ignored by the new pro- 
cess image. Signals set to be caught by the calling process image shall be set to 
the default action in the new process image (see <signal.h> §3.3.1). 

If the set-user-ID mode bit of the new process image file is set (see chmod() 
§5.6.4), the effective user ID of the new process image is set to the owner ID of 
the new process image file. Similarly, if the set-group-ID mode bit of the new 
process image file is set, the effective group ID of the new process image is set to 
the group ID of the new process image file. The real user ID, real group ID, and 
supplementary group IDs of the new process image remain the same as those of 
the calling process image. If {_POSIX_SAVED_IDS} is defined, the effective user 
ID and effective group ID of the new process image shall be saved (as the saved 
set-user-ID and the saved set-group-ID) for use by the setuid () function. 

The new process image also inherits the following attributes from the calling 
process image: 

(1) process ID 

(2) parent process ID 

(3) process group ID 

(4) session membership 

(5) real user ID 

(6) real group ID 

(7) supplementary group IDs 

(8) time left until an alarm clock signal (see alarm() §3.4.1) 
(9) current working directory 

(10) root directory 

(11) file mode creation mask (see umask() §5.3.3) 

(12) process signal mask (see sigprocmask() §3.3.5) 

(13) pending signals (see sigpending () §3.3.6) 

(14) tms_utime, tms_stime, tms_cutime, and tms_cstime (see times() §4.5.2) 

All process attributes defined by this standard and not specified in this sec- 
tion shall be the same in the new and old process images. The inheritance of 
process attributes not defined by this standard is implementation-defined. 

Upon successful completion, the exec functions shall mark for update the 
st_atime field of the file. If the exec function failed but was able to locate the 
process image file, whether the st_atime field is marked for update is unspeci- 
fied. Should the exec function succeed, the process image file shall be considered 
to have been open()-ed. The corresponding close() shall be considered to occur 
at a time after this open, but before process termination or successful comple- 
tion of a subsequent call to one of the exec functions. 

3.1.2.3 Returns. If one of the exec functions returns to the calling process 
image, an error has occurred; the return value shall be -1, and errno shall be set 
to indicate the error. 
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3.1.2.4 Errors. If any of the following conditions occur, the exec functions 
shall return —1 and set errno to the corresponding value: 

[E2BIG] The number of bytes used by the new process image’s argument 
list and environment list is greater than the system-imposed 
limit of {ARG_MAX} bytes. 

[EACCES] Search permission is denied for a directory listed in the new 
process image file’s path prefix, or the new process image file 
denies execution permission, or the new process image file is 
not a regular file and the implementation does not support exe- 
cution of files of its type. 

[ENAMETOOLONG] 

The length of the path or file arguments, or an element of the 
environment variable PATH prefixed to a file, exceeds 
{PATH MAX}, or a pathname component is longer than 
{NAME_MAX} and {_POSIX_NO_TRUNC} is in effect for that file. 

[ENOENT] One or more components of the new process image file’s path- 
name do not exist, or the path or file argument points to an 
empty string. 

[ENOTDIR] A component of the new process image file’s path prefix is not a 
directory. 

If any of the following conditions occur, the execl(), execuv(), execle(), and 
execve() functions shall return —1 and set errno to the corresponding value: 

[ENOEXEC] The new process image file has the appropriate access permis- 
sion, but is not in the proper format. 

For each of the following conditions, if the condition is detected, the exec func- 
tions shall return —1 and return the corresponding value in errno: 

[ENOMEM] The new process image requires more memory than is allowed 
by the hardware or system-imposed memory management con- 
straints. 

3.1.2.5 References. alarm() §3.4.1, chmod() §5.6.4, _exit() §3.2.2, fentlO 
§6.5.2, fork() §3.1.1, setuid() §4.2.2, <signal.h> §3.3.1, sigprocmask() §3.3.5, 
sigpending () §3.3.6, stat() §5.6.2, <sys/stat.h> §5.6.1, times() §4.5.2, umask() 
§5.3.3, Environment Description §2.7. 


3.2 Process Termination. There are two kinds of process termination: 
(1) Normal termination occurs by a return from main() or when requested 
with the exit() or _exit() functions. 
(2) Abnormal termination occurs when requested by the abort() function or 
some signals are received (see <signal.h> §3.3.1). 

The exit() and abort() functions shall be as described in the C Standard (see C 
Language Standard §A.2.2). Both exit() and abort() shall terminate a process 
with the consequences specified in _exit() §3.2.2, except that the status made 
available to wait() or waitpid() by abort() shall be that of a process terminated 
by the SIGABRT signal. 

A parent process can suspend its execution to wait for termination of a child 
process with the wait() or waitpid() functions. 
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3.2.1 Wait for Process Termination. 
Functions: wait(), waitpid() 
3.2.1.1 Synopsis. 


#include <sys/types.h> 
#include <sys/wait.h> 


pid_t wait(stat_loc) 
int *stat_loc; 


pid_t waitpid (pid, stat_loc, options) 
pid_t pid; 

int *stat_loc; 

int options; 


3.2.1.2 Description. The wait() and waitpid() functions allow the calling 
process to obtain status information pertaining to one of its child processes. 
Various options permit status information to be obtained for child processes that 
have terminated or stopped. If status information is available for two or more 
child processes, the order in which their status is reported is unspecified. 

The wait() function shall suspend execution of the calling process until status 
information for one of its terminated child processes is available, or until 
delivery of a signal whose action is either to execute a signal-catching function 
or to terminate the process. If status information is available prior to the call to 
wait(), return shall be immediate. 

The waitpid() function shall behave identically to the wait() function, if the 
pid argument has a value of —1 and the options argument has a value of zero. 
Otherwise, its behavior shall be modified by the values of the pid and options 
arguments. 

The pid argument specifies a set of child processes for which status is 
requested. The waitpid() function shall only return the status of a child process 
from this set. 

(1) If pid is equal to —1, status is requested for any child process. In this 

respect, waitpid() is then equivalent to wait(). 

(2) If pid is greater than zero, it specifies the process ID of a single child pro- 

cess for which status is requested. 

(3) If pid is equal to zero, status is requested for any child process whose pro- 

cess group ID is equal to that of the calling process. 

(4) If pid is less than -1, status is requested for any child process whose pro- 

cess group ID is equal to the absolute value of pid. 

The options argument is constructed from the bitwise inclusive OR of zero or 
more of the following flags, defined in the header <sys/wait.h>: 

WNOHANG The waitpid() function shall not suspend execution of the 
calling process if status is not immediately available for one 
of the child processes specified by pid. 

WUNTRACED If the implementation supports job control, the status of 
any child processes specified by pid that are stopped, and 
whose status has not yet been reported since they stopped, 
shall also be reported tothe requesting process. — 
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If wait() or waitpid() return because the status of a child process is available, 
these functions shall return a value equal to the process ID of the child process. 
In this case, if the value of the argument stat_loc is not NULL, information shall 
be stored in the location pointed to by stat_loc. If and only if the status 
returned is from a terminated child process that returned a value of zero from 
main() or passed a value of zero as the status argument to _exit() or exit(), the 
value stored at the location pointed to by stat_loc shall be zero. Regardless of its 
value, this information may be interpreted using the following macros, which 
are defined in <sys/wait.h> and evaluate to integral expressions; the stat_val 
argument is the integer value pointed to by stat_loc. 

WIFEXITED(stat_val) 
Evaluates to a non-zero value if status was returned for a child 
process that terminated normally. 

WEXITSTATUS(stat_val) 
If the value of WIFEXITED(stat_val) is non-zero, this macro 
evaluates to the low-order 8 bits of the status argument that the 
child process passed to _exit() or exit(), or the value the child 
process returned from main(). 

WIFSIGNALED(stat_val) 
Evaluates to a non-zero value if status was returned for a child 
process that terminated due to the receipt of a signal that was 
not caught (see <signal.h> $3.3.1). 

WTERMSIG(stat_val) 
If the value of WIFSIGNALED(stat_val) is non-zero, this macro 
evaluates to the number of the signa! that caused the termina- 
tion of the child process. 

WIFSTOPPED(stat_val) 
Evaluates to a non-zero value if status was returned for a child 
process that is currently stopped. 

WSTOPSIG(stat_val) 
If the value of WIFSTOPPED(stat_val) is non-zero, this macro 
evaluates to the number of the signal that caused the child pro- 
cess to stop. 

If the information stored at the location pointed to by stat_loc was stored 
there by a call to the waitpid() function that specified the WUNTRACED flag, 
exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(<stat_loc), and 
WIFSTOPPED(*stat_loc) shall evaluate to a non-zero value. If the information 
stored at the location pointed to by stat_loc was stored there by a call to the 
waitpid() function that did not specify the WUNTRACED flag or by a call to the 
wait() function, exactly one of the macros WIFEXITED(*stat_loc) and 
WIFSIGNALED(*stat_loc) shall evaluate to a non-zero value. 

An implementation may define additional circumstances under which wait() 
or waitpid() reports status. This shall not occur unless the calling process or 
one of its child processes explicitly makes use of a nonstandard extension. In 
these cases the interpretation of the reported status is implementation-defined. 

If a parent process terminates without waiting for all of its child processes to 
terminate, the remaining child processes shall be assigned a new parent process 
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ID corresponding to an implementation-defined system process. 
3.2.1.3 Returns. If the wait() or waitpid() functions return because the 
status of a child process is available, these functions shall return a value equal 
to the process ID of the child process for which status is reported. If the wait() 
or waitpid() functions return due to the delivery of a signal to the calling pro- 
cess, a value of —1 shall be returned and errno shall be set to [EINTR]. If the 
waitpid() function was invoked with WNOHANG set in options, it has at least 
one child process specified by pid for which status is not available, and status is 
not available for any process specified by pid, a value of zero shall be returned. 
Otherwise, a value of —1 shall be returned, and errno shall be set to indicate the 
error. 
3.2.1.4 Errors. If any of the following conditions occur, the wait() func- 
tion shall return —1 and set errno to the corresponding value: 
[ECHILD] The calling process has no existing unwaited-for child 
processes. 
[EINTR] The function was interrupted by a signal. The value of the loca- 
tion pointed to by stat_loc is undefined. 
If any of the following conditions occur, the waitpid() function shall return -1 
and set errno to the corresponding value: 
[ECHILD] The process or process group specified by pid does not exist or is 
not a child of the calling process. 
[EINTR] The function was interrupted by a signal. The value of the loca- 
tion pointed to by stat_loc is undefined. 
[EINVAL] The value of the options argument is not valid. 
3.2.1.5 References. _exit() §3.2.2, fork() §3.1.1, pause() §3.4.2, a) 
§4.5.2, <signal.h> §3.3.1. 


3.2.2 Terminate a Process. 
Function: _exit() 
3.2.2.1 Synopsis. 


void _exit (status) 
int status; 


3.2.2.2 Description. The _exit() function shall terminate the calling pro- 
cess with the following consequences: 

(1) All open file descriptors and directory streams in the calling process are 
closed. 
(2) If the parent process of the calling process is executing a wait() or wait- 
pid(), it is notified of the calling process’s termination and the low order 8 
bits of status are made available to it; see wait §3.2.1. 
(3) If the parent process of the calling process is not executing a wait() or 
waitpid() function, the exit status code is saved for return to the parent pro- 
cess whenever the parent process executes an appropriate subsequent wait() 
or waitpid (). 
(4) Termination of a process does not directly terminate its children. The 
sending of a SIGHUP signal as described below indirectly terminates children 
in some circumstances. Children of a terminated process shall be assigned a 
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new parent process ID, corresponding to an implementation-defined system 
process. 
(5) If the implementation supports the SIGCHLD signal, a SIGCHLD signal 
shall be sent to the parent process. 
(6) If the process is a controlling process, the SIGHUP signal shall be sent to 
each process in the foreground process group of the controlling terminal 
belonging to the calling process. 
(7) If the process is a controlling process, the controlling terminal associated 
with the session is disassociated from the session, allowing it to be acquired 
by a new controlling process. 
(8) If the implementation supports job control, and if the exit of the process 
causes a process group to become orphaned, and if any member of the 
newly-orphaned process group is stopped, then a SIGHUP signal followed by 
a SIGCONT signal shall be sent to each process in the newly-orphaned pro- 
cess group. 
These consequences shall occur on process termination for any reason. 
3.2.2.3 Returns. The _exit() function cannot return to its caller. 
3.2.2.4 References. close() §6.3.1, sigaction() §3.3.4, wait §3.2.1. 


3.3 Signals. 


3.3.1 Signal Concepts. 
3.3.1.1 Signal Names. The <signal.h> header declares the sigset_t type 
and the sigaction structure. It also defines the following symbolic constants, 
each of which expands to a distinct constant expression of the type void(*)(), 
whose value matches no declarable function. 


Symbolic 
Constant 
SIG_DFL __ request for default signal handling 
SIG_IGN _ request that signal be ignored 


Description 


The type sigset_t is used to represent sets of signals. It is always an integral 
or structure type. Several functions used to manipulate objects of type sigset_t 
are defined in sigsetops §3.3.3. 

The <signal.h> header also declares the constants that are used to refer to 
the signals that occur in the system. Each of the signals defined by this stan- 
dard and supported by the implementation shall have distinct, positive integral 
values. The value zero is reserved for use as the null signal (see Rill() §3.3.2). 
An implementation may define additional signals that may occur in the system. 

The constants shown in Table 3-1 shall be supported by all implementations. 

The constants shown in Table 3-2 shall be defined by all implementations. 
However, implementations that do not support job control are not required to 
support these signals. If these signals are supported by the implementation, 
they shall behave in accordance with this standard. Otherwise, the implemen- 
tation shall not generate these signals and attempts to send these signals or to 
examine or specify their actions shall return an error condition. See Rill() §3.3.2 
and sigaction() §3.3.4. 
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Symbolic 


Constant 


SIGABRT 
SIGALRM 
SIGFPE 


SIGHUP 


SIGILL 
SIGINT 


SIGKILL 
SIGPIPE 
SIGQUIT 


SIGSEGV 


SIGTERM 
SIGUSR1 
SIGUSR2 


Symbolic 
Constant 
SIGCHLD 


SIGCONT 
SIGSTOP 
SIGTSTP 


SIGTTIN 


SIGTTOU 
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Table 3-1. Required Signals 


Description 


Abnormal termination signal, such as is initiated by 
the abort() function (as defined in the C Standard). 


Timeout signal, such as initiated by the alarm() func- 
tion (see alarm() §3.4.1). 


Erroneous arithmetic operation, such as division by 
zero or an operation resulting in overflow. 


Hangup detected on controlling terminal (see Modem 
Disconnect §7.1.1.10) or death of controlling process 
(see _exit() §3.2.2). 


Detection of an invalid hardware instruction. 


Interactive attention signal (see Special Characters 
Side Ue) 


Termination signal (cannot be caught or ignored). 
Write on a pipe with no readers (see write() §6.4.2). 
Interactive termination signal (see Special Charac- 
ters §7.1.1.9). 

Detection of an invalid memory reference. 
Termination signal. 

Reserved as application-defined signal 1. 

Reserved as application-defined signal 2. ° 


Table 3-2. Job Control Signals 


Description 


Child process terminated or stopped. 


Continue if stopped. 

Stop signal (cannot be caught or ignored). 

Interactive stop signal (see Special Characters 
§7.1.1.9). 

Read from control terminal attempted by a member of 
a background process group (see Terminal Access 
Control §7.1.1.4). 

Write to control terminal attempted by a member of a 


background process group (see Terminal Access 
Control §7.1.1.4). 
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Default actions for Tables 3-1 and 3-2 are as follows: 

1 Abnormal termination of the process. 

2 Ignore the signal. 

3 Stop the process. 

4 Continue the process if it is currently stopped; otherwise, ignore the 

signal. 

3.3.1.2 Signal Generation and Delivery. A signal is said to be gen- 
erated for (or sent to) a process when the event that causes the signal first 
occurs. Examples of such events include detection of hardware faults, timer 
expiration, and terminal activity, as well as the invocation of the Aill() function. 
In some circumstances, the same event generates signals for multiple processes. 

Each process has an action to be taken in response to each signal defined by 
the system (see Signal Actions §3.3.1.3). A signal is said to be delivered to a 
process when the appropriate action for the process and signal is taken. 

During the time between the generation of a signal and its delivery, the signal 
is said to be pending. Ordinarily, this interval cannot be detected by an applica- 
tion. However, a signal can be blocked from delivery to a process. If the action 
associated with a blocked signal is anything other than to ignore the signal, and 
if that signal is generated for the process, the signal shall remain pending until 
either it is unblocked or the action associated with it is set to ignore the the sig- 
nal. If the action associated with a blocked signal is to ignore the signal and if 
that signal is generated for the process, it is unspecified whether the signal is 
discarded immediately upon generation or remains pending. 

Each process has a signal mask that defines the set of signals currently 
blocked from delivery to it. The signal mask for a process is initialized from 
that of its parent. The sigaction(), sigprocmask(), and sigsuspend() functions 
control the manipulation of the signal mask. 

The determination of which action is taken in response to a signal is made at 
the time the signal is delivered, allowing for any changes since the time of gen- 
eration. This determination is independent of the means by which the signal 
was originally generated. If a subsequent occurrence of a pending signal is gen- 
erated, it is implementation-defined as to whether the signal is delivered more 
than once. The order in which multiple, simultaneously pending signals are 
delivered to a process is unspecified. 

When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated 
for a process, any pending SIGCONT signals for that process shall be discarded. 
Conversely, when SIGCONT is generated for.a process, all pending stop signals 
for that process shall be discarded. When SIGCONT is generated for a process 
that is stopped, the process shall be continued, even if the SIGCONT signal is 
blocked or ignored. If SIGCONT is blocked and not ignored, it shall remain 
pending until it is either unblocked or a stop signal is generated for the process. 

An implementation shall document any conditions not specified by this stan- 
dard under which the implementation generates signals. (See Documentation 
€2.2.9/2.) 
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3.3.1.3 Signal Actions. There are three types of actions that can be asso- 
ciated with a signal: SIG_DFL, SIG_IGN, or a pointer to a function. Initially, all 
signals shall be set to SIG_DFL or SIG_IGN prior to entry of the main() routine 
(see exec §3.1.2). The actions prescribed by these values are as follows: 
(1) SIG_DFL — signal-specific default action 
(a) The default actions for the signals defined in this standard are speci- 
fied in the preceding tables. 
(b) If the default action is to stop the process, the execution of that pro- 
cess is temporarily suspended. When a process stops, a SIGCHLD signal 
shall be generated for its parent process, unless the parent process has 
set the SA_NOCLDSTOP flag (see sigaction() §3.3.4). While a process is 
stopped, any additional signals that are sent to the process shall not be 
delivered until the process is continued, except SIGKILL, which always 
terminates the receiving process. A process that is a member of an 
orphaned process group shall not be allowed to stop in response to the 
SIGTSTP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of 
these signals would stop such as process, the signal shall be discarded. 
(c) Setting a signal action to SIG_DFL for a signal that is pending, and 
whose default action is to ignore the signal (for example, SIGCHLD), shall 
cause the pending signal to be discarded, whether or not it is blocked. 
(2) SIG_IGN — ignore signal 
(a) Delivery of the signal shall have no effect on the process. The 
behavior of a process is undefined after it ignores a SIGFPE, SIGILL, or 
SIGSEGV signal that was not generated by the Aill() function or the 
raise() function defined by the C Standard. 
(b) The system shall not allow the action for the signals SIGKILL or SIG- 
STOP to be set to SIG_IGN. 
(c) Setting a signal action to SIG_IGN for a signal that is pending shall 
cause the pending signal to be discarded, whether or not it is blocked. 
(d) If a process sets the action for the SIGCHLD signal to SIG_IGN, the 
behavior is unspecified. 
(3) pointer to a function — catch signal 
(a) On delivery of the signal, the receiving process is to execute the 
signal-catching function at the specified address. After returning from 
the signal-catching function, the receiving process shall resume execution 
at the point at which it was interrupted. 
(b) The signal-catching function shall be entered as a C language function 
call as follows: 


void func (signo) 
int signo; 


where func is the specified signal-catching function and signo is the sig- 
nal number of the signal being delivered. 

(c) The behavior of a process is undefined after it returns normally from a 
signal-catching function for a SIGFPE, SIGILL, or SIGSEGV signal that 
was not generated by the &ill() function or the raise() function defined by 
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the C Standard. 
(d) The system shall not allow a process to catch the signals SIGKILL and 
SIGSTOP. 


(e) If a process establishes a signal-catching function for the SIGCHLD sig- 
nal while it has a terminated child process for which it has not waited, it 
is unspecified whether a SIGCHLD signal is generated to indicate that 
child process. 

(f) When signal-catching functions are invoked asynchronously with pro- 
cess execution, the behavior of some of the functions defined by this stan- 
dard is unspecified if they are called from a signal-catching function. The 
following table defines a set of functions that shall be reentrant with 
respect to signals (that is, applications may invoke them, without restric- 
tion, from signal-catching functions): 


_exit() getegid() rename() tcdrain() 
access() geteuid() rmdir() tcflow () 
alarm() getgid() setgid() tcflush() 
cfgetispeed()  getgroups() setpgid() tegetattr () 
cfgetospeed() getpgrp() setsid() tegetpgrp() 
cfsetispeed()  getpid() setuid() tesendbreak() 
cfsetospeed()  getppid() sigaction () tcsetattr () 
chdir() getuid() sigaddset () tcsetpgrp () 
chmod () kill() sigdelset () time() 
chown() link() sigemptyset() times() 
close() lseek() sigfillset() umask() 
creat() mkdir () sigismember() uname() 
dup2() mkfifo() sigpending () unlink() 
dup() open() sigprocmask()  ustat() 
execle() pathconf() sigsuspend() utime() 
execve () pause() sleep () wait() 
fentlQ pipe() stat() waitpid () 
fork() read() sysconf() write () 
fstat() 


All IEEE Std 1003.1-1988 functions not in the above table and all func- 
tions defined in the C Standard not stated to be callable from a signal- 
catching function are considered to be unsafe with respect to signals. If 
any function that is unsafe is interrupted by a signal-catching function 
that then calls any function that is unsafe, the behavior is undefined. 

3.3.1.4 Signal Effects on Other Functions. Signals affect the behavior 
of certain functions defined by this standard if delivered to a process while it is 
executing such a function. If the action of the signal is to terminate the process, 
the process shall be terminated and the function shall not return. If the action 
of the signal is to stop the process, the process shall stop until continued or ter- 
minated. Generation of a SIGCONT signal for the process causes the process to 
be continued, and the original function shall continue at the point where the 
process was stopped. If the action of the signal is to invoke a signal-catching 
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function, the signal-catching function shall be invoked; in this case the original 
function is said to be interrupted by the signal. If the signal-catching function 
executes a return, the behavior of the interrupted function shall be as 
described individually for that function. Signals that are ignored shall not 
affect the behavior of any function; signals that are blocked shall not affect the 
behavior of any function until they are delivered. 


3.3.2 Send a Signal to a Process. 
Function: kill() 
3.3.2.1 Synopsis. 


#include <sys/types.h> 
#include <signal.h> 


int kill (pid, sig) 

pid_t pid; 

int sig; 

3.3.2.2 Description. The ill() function shall send a signal to a process 
or a group of processes specified by pid. The signal to be sent is specified by sig 
and is either one from the list given in <signal.h> §3.3.1 or zero. If sig is zero 
(the null signal), error checking is performed but no signal is actually sent. The 
null signal can be used to check the validity of pid. 

For a process to have permission to send a signal to a process designated by 
pid, the real or effective user ID of the sending process must match the real or 
effective user ID of the receiving process, unless the sending process has 
appropriate privileges. If {_POSIX_SAVED_IDS} is defined, the saved set-user-ID 
of the receiving process shall be checked in place of its effective user ID. If a 
receiving process’s effective user ID has been altered through use of the S_ISUID 
mode bit (see <sys/stat.h> §5.6.1), the implementation may still permit the 
application to receive a signal sent by the parent process or by a process with 
the same real user ID. 

If pid is greater than zero, sig shall be sent to the process whose process ID is 
equal to pid. 

If pid is zero, sig shall be sent to all processes (excluding an implementation- 
defined set of system processes) whose process group ID is equal to the process 
group ID of the sender, and for which the process has permission to send a sig- 
nal. 

If pid is —1, the behavior of the kill() function is unspecified. 

If pid is negative, but not —1, sig shall be sent to all processes whose process 
group ID is equal to the absolute value of pid, and for which the process has per- 
mission to send a signal. 

If the value of pid causes sig to be generated for the sending process, and if 
sig is not blocked, either sig or at least one pending unblocked signal shall be 
delivered to the sending process before the ill() function returns. 

If the implementation supports the SIGCONT signal, the user ID tests 
described above shall not be applied when sending SIGCONT to a process that is 
a member of the same session as the sending process. 
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An implementation that provides extended security controls may impose 
further implementation-defined restrictions on the sending of signals, including 
the null signal. In particular, the system may deny the existence of some or all 
of the processes specified by pid. 

The &ill() function is successful if the process has permission to send sig to 
any of the processes specified by pid. If the kill() function fails, no signal shall 
be sent. 

3.3.2.8 Returns. Upon successful completion, the function shall return a 
value of zero. Otherwise, a value of —1 shall be returned and errno shall be set 
to indicate the error. 

3.3.2.4 Errors. If any of the following conditions occur, the kill() func- 
tion shall return —1 and set errno to the corresponding value: 

[EINVAL] The value of the sig argument is an invalid or unsupported sig- 
nal number. 

[EPERM] The process does not have permission to send the signal to any 
recelving process. 

[ESRCH] No process or process group can be found corresponding to that 
specified by pid. 

3.3.2.5 References. getpid() §4.1.1, setsid() §4.3.2, sigaction() §3.3.4, 
<signal.h> §3.3.1. 


3.3.0 Manipulate Signal Sets. 
Functions: sigemptyset(), sigfillset(), sigaddset(), sigdelset(), sigismember () 
3.3.3.1 Synopsis. 


#include <signal.h> 


int sigemptyset (set) 
sigset_t «set; 


int sigfillset (set) 
sigset_t «set; 


int sigaddset (set, signo) 
sigset_t «set; 
int signo; 


int sigdelset (set, signo) 
sigset_t *set; 
int signo; 


int sigismember (set, signo) 
sigset_t «set; 
int signo; 


3.0.0.2 Description. The sigsetops primitives manipulate sets of signals. 
They operate on data objects addressable by the application, not on any set of 
signals known to the system, such as the set blocked from delivery to a process 
or the set pending for a process (see <signal.h> §3.3.1). 
The sigemptyset() function initializes the signal set pointed to by the argu- 
ment set, such that all signals defined in this standard are excluded. 
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The sigfillset() function initializes the signal set pointed to by the argument 
set, such that all signals defined in this standard are included. 

Applications shall call either sigemptyset() or sigfillset() at least once for each 
object of type sigset_t prior to any other use of that object. If such an object is 
not initialized in this way, but is nonetheless supplied as an argument to any of 
the sigaddset(), sigdelset(), sigismember(), sigaction(), sigprocmask(), sigpend- 
ing (), or sigsuspend() functions, the results are undefined. 

The sigaddset() and sigdelset() functions respectively add and delete the indi- 
vidual signal specified by the value of the argument signo from the signal set 
pointed to by the argument set. 

The sigismember() function tests whether the signal specified by the value of 
the argument signo is a member of the set pointed to by the argument set. 

3.3.3.3 Returns. Upon successful completion, the sigismember () function 
returns a value of one if the specified signal is a member of the specified set, or 
a value of zero if it is not. Upon successful completion, the other functions 
return a value of zero. For all of the above functions, if an error is detected, a 
value of —1 is returned and errno is set to indicate the error. 

3.3.3.4 Errors. For each of the following conditions, if the condition is 
detected, the sigaddset(), sigdelset(), and sigismember() functions shall return 
—1 and set errno to the corresponding value: 

[EINVAL] The value of the signo argument is an invalid or unsupported 
signal number. 

3.3.3.5 References. sigaction() §3.3.4, <signal.h> §3.3.1, sigpending () 

§3.3.6, sigprocmask() §3.3.5, sigsuspend () §3.3.7. 


3.3.4 Examine and Change Signal Action. 
Function: sigaction() 
3.3.4.1 Synopsis. 


#include <signal.h> 


int sigaction (sig, act, oact) 

int sig; 

struct sigaction «act, *oact; 

3.3.4.2 Description. The sigaction() function allows the calling process 
to examine or specify (or both) the action to be associated with a specific signal. 
The argument sig specifies the signal; acceptable values are defined in 
<signal.h> §3.3.1. 

The structure sigaction, used to describe an action to be taken, is defined in 

the header <signal.h> to include at least the following members: 


Member Member — 
Description 
Type Name 
void (*)() sa_handler SIG_DFL, SIG_IGN, or pointer to a function. 
sigset_t sa_mask Additional set of signals to be blocked. during execu- 
tion of signal-catching function. 
int sa_flags Special flags to affect behavior of signal. 


64 Process Primitives 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003. 1-1988 


If the argument act is not NULL, it points to a structure specifying the action to 
be associated with the specified signal. If the argument oact is not NULL, the 
action previously associated with the signal is stored in the location pointed to 
by the argument oact. If the argument act is NULL, signal handling is 
unchanged by this function call; thus, the call can be used to enquire about the 
current handling of a given signal. The sa_handler field of the sigaction struc- 
ture identifies the action to be associated with the specified signal. If the 
sa_handler field specifies a signal-catching function, the sa_mask field identifies 
a set of signals that shall be added to the process’s signal mask before the 
signal-catching function is invoked. The SIGKILL and SIGSTOP signals shall not 
be added to the signal mask using this mechanism; this restriction shall be 
enforced by the system without causing an error to be indicated. 

The sa_flags field can be used to modify the behavior of the specified signal. 

The following flag bit, defined in the header <signal.h>, can be set in 
sa_flags: 


Symbolic 
___Constant 
SA_NOCLDSTOP Do not generate SIGCHLD when children stop 


If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and the 
implementation supports the SIGCHLD signal, a SIGCHLD signal shall be gen- 
erated for the calling process whenever any of its child processes stop. If sig is 
SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, the implementation 
shall not generate a SIGCHLD signal in this way. 

When a signal is caught by a signal-catching function installed by the sigac- 
tion() function, a new signal mask is calculated and installed for the duration of 
the signal-catching function (or until a call to either the sigprocmask() or sig- 
suspend() function is made). This mask is formed by taking the union of the 
current signal mask and the value of the sa_maszk for the signal being delivered, 
and then including the signal being delivered. If and when the user’s signal 
handler returns normally, the original signal mask is restored. 

Once an action is installed for a specific signal, it remains installed until 
another action is explicitly requested (by another call to the sigaction() func- 
tion), or until one of the exec functions is called. 

If the previous action for sig had been established by the signal() function, 
defined in the C Standard, the values of the fields returned in the structure 
pointed to by oact are unspecified, and in particular oact->su_handler is not 
necessarily the same value passed to the signal() function. However, if a 
pointer to the same structure or a copy thereof is passed to a subsequent call to 
the sigaction() function via the act argument, handling of the signal shall be as 
if the original call to the signal() function were repeated. 

If the sigaction() function fails, no new signal handler is installed. 

3.3.4.3 Returns. Upon successful completion a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 


Description 
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3.3.4.4 Errors. If any of the following conditions occur, the sigaction() 
function shall return —1 and set errno to the corresponding value: 

[EINVAL] The value of the sig argument is an invalid or unsupported sig- 
nal number, or an attempt was made to catch a signal that can- 
not be caught or to ignore a signal that cannot be ignored. See 
<signal.h> §3.3.1. 

3.3.4.5 References. kill() §3.3.2, <signal.h> §3.3.1, sigprocmask() 
§3.3.5, sigsetops §3.3.3, sigsuspend() §3.3.7. 


3.3.5 Examine and Change Blocked Signals. 
Function: sigprocmask() 
3.3.5.1 Synopsis. 


#include <signal.h> 


int sigprocmask (how, set, oset) 
int how; 
sigset_t *set, *oset; 


3.3.5.2 Description. The sigprocmask() function is used to examine or 
change (or both) the calling process’s signal mask. If the value of the argument 
set is not NULL, it points to a set of signals to be used to change the currently 
blocked set. 
The value of the argument how indicates the manner in which the set is 
changed, and shall consist of one of the following values, as defined in the 
header <signai.h> §3.3.1: 


Name ” Description 

SIG_BLOCK The resulting set shall be the union of the current set 
and the signal set pointed to by the argument set. 

SIG_LUNBLOCK _ The resulting set shall be the intersection of the 
current set and the complement of the signal set 
pointed to by the argument set. 

SIG_SETMASK _ The resulting set shall be the signal set pointed to by 
the argument set. 


If the argument oset is not NULL, the previous mask is stored in the space 
pointed to by oset. If the value of the argument set is NULL, the value of the 
argument how is not significant and the process’s signal mask is unchanged by 
this function call; thus, the call can be used to enquire about currently blocked 
signals. 

If there are any pending unblocked signals after the call to the sigprocmask() 
function, at least one of those signals shall be delivered before the sigprocmask() 
function returns. 

It is not possible to block the SIGKILL and SIGSTOP signals; this shall be 
enforced by the system without causing an error to be indicated. 

If any of the SIGFPE, SIGILL, or SIGSEGV signals are generated while they are 
blocked, the result is undefined, unless the signal was generated by a call to the 
kill() function or the raise() function defined by the C Standard. 
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If the sigprocmask() function fails, the process’s signal mask is not changed 

by this function call. 

3.3.5.3 Returns. Upon successful completion a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 

3.3.5.4 Errors. If any of the following conditions occur, the sigproc- 
mask() function shall return —-1 and set errno to the corresponding value: 

[EINVAL] The value of the how argument is not equal to one of the 

defined values. 

3.3.5.5 References. sigaction() §3.3.4, <signal.h> §3.3.1, sigpending () 

§3.3.6, sigsetops §3.3.3, sigsuspend() §3.3.7. 


3.3.6 Examine Pending Signals. 
Function: sigpending () 
3.3.6.1 Synopsis. 


#include <signal.h> 


int sigpending (set) 
sigset_t «set; 


3.3.6.2 Description. The sigpending() function shall store the set of sig- 
nals that are blocked from delivery and pending for the calling process, in the 
space pointed to by the argument set. 

3.3.6.3 Returns. Upon successful completion a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 

3.3.6.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the sigpending() function. Some errors may be 
detected under implementation-defined conditions. 

3.3.6.5 References. <signal.h> §3.3.1, sigprocmask() §3.3.5, sigsetops 
She 2) 


3.3.7 Wait for a Signal. 
Function: sigsuspend() 
3.3.7.1 Synopsis. 


#include <signal.h> 


int sigsuspend (sigmask) 
sigset_t *sigmask; 


3.3.7.2 Description. The sigsuspend() function replaces the process’s 
signal mask with the set of signals pointed to by the argument sigmask and 
then suspends the process until delivery of a signal whose action is either to 
execute a signal-catching function or to terminate the process. 

If the action is to terminate the process, the sigsuspend() function shall not 
return. If the action is to execute a signal-catching function, the sigsuspend() 
shall return after the signal-catching function returns, with the signal mask 
restored to the set that existed prior to the sigsuspend() call. 

It is not possible to block those signals that cannot be ignored, as documented 
in <signal.h> §3.3.1; this shall be enforced by the system without causing an 
error to be indicated. 
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3.3.7.3 Returns. Since the sigsuspend() function suspends process exe- 
cution indefinitely, there is no successful completion return value. A value of -1 
is returned and errno is set to indicate the error. 

3.3.7.4 Errors. If any of the following conditions occur, the sigsuspend() 
function shall return —1 and set errno to the corresponding value: 

[EINTR] A signal is caught by the calling process and control is returned 
from the signal-catching function. 

3.3.7.5 References. pause() §3.4.2, sigaction() §3.3.4, <signal.h> §3.3.1, 

sigpending() §3.3.6, sigprocmask() §3.3.5, sigsetops §3.3.3. 


3.4 Timer Operations. A process can suspend itself for a specific period of 
time with the sleep() function or suspend itself indefinitely with the pause() 
function until a signal arrives. The alarm() function schedules a signal to 
arrive at a specific time, so a pause() suspension need not be indefinite. 


3.4.1 Schedule Alarm. 
Function: alarm() 
3.4.1.1 Synopsis. 


unsigned int alarm (seconds ) 
unsigned int seconds; 


3.4.1.2 Description. The alarm() function shall cause the system to send 
the calling process a SIGALRM signal after the number of real time seconds 
specified by seconds have elapsed. 

Processor scheduling delays may cause the process to not actually begin han- 
dling the signal until after the desired time. 

Alarm requests are not stacked; only one SIGALRM generation can be 
scheduled in this manner; if the SIGALRM has not yet been generated, the call 
will result in rescheduling the time at which the SIGALRM will be generated. 

If seconds is zero, any previously-made alarm() request is canceled. 

3.4.1.3 Returns. The alarm() function shall return the amount of time 
remaining in seconds before the system is scheduled to generate the SIGALRM 
signal, or zero if there is no previous alarm() request. 

3.4.1.4 Errors. The alarm() function is always successful, and no return 
value is reserved to indicate an error. 

3.4.1.5 References. exec §3.1.2, fork() §3.1.1, pause() §3.4.2, sigaction() 
§3.3.4, <signal.h> §3.3.1. 


3.4.2 Suspend Process Execution. 
Function: pause() 
3.4.2.1 Synopsis. 


int pause ( ) 


3.4.2.2 Description. The pause() function suspends the calling process 

until delivery of a signal whose action is either to execute a signal-catching 
function or to terminate the process. 

If the action is to terminate the process, the pause() function shall not return. 
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If the action is to execute a signal-catching function, the pause() function 
shall return after the signal-catching function returns. 
3.4.2.3 Returns. Since the pause() function suspends process execution 
indefinitely, there is no successful completion return value. A value of —1 is 
returned and errno is set to indicate the error. 
3.4.2.4 Errors. If any of the following conditions occur, the pause() func- 
tion shall return —1 and set errno to the corresponding value: 
[EINTR] A signal is caught by the calling process and control is returned 
from the signal-catching function. 
3.4.2.5 References. alarm() §3.4.1, RillQ §3.3.2, wait §3.2.1, Signal 
Effects on Other Functions §3.3.1.4. 


3.4.3 Delay Process Execution. 
Function: sleep() 
3.4.3.1 Synopsis. 


unsigned int sleep (seconds) 
unsigned int seconds; 


3.4.3.2 Description. The sleep() function shall cause the current process 
to be suspended from execution until either the number of real time seconds 
specified by the argument seconds have elapsed or a signal is delivered to the 
calling process and its action is to invoke a signal-catching function or to ter- 
minate the process. The suspension time may be longer than requested due to 
the scheduling of other activity by the system. 

If a SIGALRM signal is generated for the calling process during execution of 
the sleep() function, and if the SIGALRM signal is being ignored or blocked from 
delivery, it is unspecified whether sleep() returns when the SIGALRM signal is 
scheduled. If the signal is being blocked, it is also unspecified whether it 
remains pending after the sleep() function returns or it is discarded. 

If a SIGALRM signal is generated for the calling process during execution of 
the sleep() function, except as a result of a prior call to the alarm() function, 
and if the SIGALRM signal is not being ignored or blocked from delivery, it is 
unspecified whether that signal has any effect other than causing the sleep() 
function to return. 

If a signal-catching function interrupts the sleep() function and examines or 
changes either the time a SIGALRM is scheduled to be generated, the action 
associated with the SIGALRM signal, or whether the SIGALRM signal is blocked 
from delivery, the results are unspecified. 

If a signal-catching function interrupts the sleep() function and calls the 
siglongjmp() or longjmp() function to restore an environment saved prior to the 
sleep() call, the action associated with the SIGALRM signal and the time at 
which a SIGALRM signal is scheduled to be generated are unspecified. It is also 
unspecified whether the SIGALRM signal is blocked, unless the process’s signal 
mask is restored as part of the environment (see sigsetjmp() §8.3.1). 
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3.4.3.3 Returns. If the sleep() function returns because the requested 
time has elapsed, the value returned shall be zero. If the sleep() function 
returns due to delivery of a signal, the value returned shall be the unslept 
amount (the requested time minus the time actually slept) in seconds. 

3.4.3.4 Errors. The sleep() function is always successful, and no return 
value is reserved to indicate an error. 

3.4.3.5 References. alarm() §3.4.1, pause() §3.4.2, sigaction() §3.3.4. 
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4.1 Process Identification. 


4.1.1 Get Process and Parent Process IDs. 
Functions: getpid(), getppid() 
4.1.1.1 Synopsis. 


#include <sys/types.h> 
pid_t getpid () 
pid_t getppid () 


4.1.1.2 Description. The getpid() function returns the process ID of the 
calling process. 
The getppid() function returns the parent process ID of the calling process. 
4.1.1.3 Returns. See Description. 
4.1.1.4 Errors. The getpid() and getppid() functions are always success- 
ful, and no return value is reserved to indicate an error. 
4.1.1.5 References. exec §3.1.2, fork() §3.1.1, kill §3.3.2. 


4.2 User Identification. 


4.2.1 Get Real User, Effective User, Real Group, and Effective Group 
IDs. 
Functions: getuid(), geteuid(), getgid(), getegid() 
4.2.1.1 Synopsis. 


#include <sys/types.h> 
uid_t getuid () 

uid_t geteuid () 

gid_t getgid () 

gid_t getegid () 


4.2.1.2 Description. The getuid() function returns the real user ID of the 
calling process. 
The geteuid() function returns the effective user ID of the calling process. 
The getgid() function returns the real group ID of the calling process. 
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The getegid() function returns the effective group ID of the calling process. 


4.2.1.3 Returns. See Description. 
4.2.1.4 Errors. The getuid(), geteuid(), getgid(), and getegid() functions 


are always successful, and no return value is reserved to indicate an error. 


4.2.1.5 References. setuid() §4.2.2. 
4.2.2 Set User and Group IDs. 


Functions: setuid(), setgid() 


4.2.2.1 Synopsis. 
#include <sys/types.h> 


int setuid (uid) 
uid_t uid; 


int setgid (gid) 
gid_t gid; 


4.2.2.2 Description. If {_POSIX_SAVED_IDS} is defined: 
(1) If the process has appropriate privileges, the setuid() function sets the 
real user ID, effective user ID, and the saved set-user-ID to wid. 
(2) If the process does not have appropriate privileges, but wid is equal to the 
real user ID or the saved set-user-ID, the setuid() function sets the effective 
user ID to wid; the real user ID and saved set-user-ID remain unchanged by 
this function call. 
(3) If the process has appropriate privileges, the setgid() function sets the 
real group ID, effective group ID, and the saved set-group-ID to gid. 
(4) If the process does not have appropriate privileges, but gid is equal to the 
real group ID or the saved set-group-ID, the setgid() function sets the effec- 
tive group ID to gid; the real group ID and saved set-group-ID remain 
unchanged by this function call. 


Otherwise: 


(1) If the process has appropriate privileges, the setuid() function sets the 
real user ID and effective user ID to uid. 

(2) If the process does not have appropriate privileges, but wid is equal to the 
real user ID, the setuid() function sets the effective user ID to wid; the real 
user ID remains unchanged by this function call. 

(3) If the process has appropriate privileges, the setgid() function sets the 
real group ID and effective group ID to gid. 

(4) If the process does not have appropriate privileges, but gid is equal to the 
real group ID, the setgid() function sets the effective group ID to gid; the real 
group ID remains unchanged by this function call. 


Any supplementary group IDs of the calling process remain unchanged by 
these function calls. 


4.2.2.3 Returns. Upon successful completion, a value of zero is returned. 


Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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4.2.2.4 Errors. If any of the following conditions occur, the setuid() func- 
tion shall return —1 and set errno to the corresponding value: 

[EINVAL] The value of the wid argument is invalid and not supported by 
the implementation. 

[EPERM] The process does not have appropriate privileges and wid does 
not match the real user ID or, if {_POSIX_SAVED_IDS} is defined, 
the saved set-user-ID. . 

If any of the following conditions occur, the setgid() function shall return —1 
and set errno to the corresponding value: 

[EINVAL] The value of the gid argument is invalid and not supported by 
the implementation. 

[EPERM] The process does not have appropriate privileges and gid does 
not match the real group ID or, if {.POSIX_SAVED_IDS} is 
defined, the saved set-group-ID. 

4.2.2.5 References. exec §3.1.2, getuid() §4.2.1. 


4.2.3 Get Supplementary Group IDs. 
Function: getgroups() 
4.2.3.1 Synopsis. 


#include <sys/types.h> 


int getgroups (gidsetsize, grouplist) 
int gidsetsize; 
gid_t grouplist[]; 


4.2.3.2 Description. The getgroups() function fills in the array grouplist 
with the supplementary group IDs of the calling process. The gidsetsize argu- 
ment specifies the number of elements in the supplied array grouplist. The 
actual number of supplementary group IDs is returned. The values of array 
entries with indices larger than or equal to the returned value are undefined. 

It is unspecified whether the effective group ID of the calling process is 
included in or omitted from the returned list of supplementary group IDs. 

As a special case, if the gidsetsize argument is zero, getgroups() returns the 
number of supplemental group IDs associated with the calling process without 
modifying the array pointed to by the grouplist argument. 

4.2.3.3 Returns. Upon successful completion, the number of supplemen- 
tary group IDs is returned. This value is zero if {NGROUPS_MAX} is zero. A 
return value of —1 indicates failure and errno is set to indicate the error. 

4.2.3.4 Errors. If any of the following conditions occur, the getgroups() 
function shall return —1 and set errno to the corresponding value: 

[EINVAL] The gidsetsize argument is not equal to zero and is less than the 
number of supplementary group IDs. 
4.2.3.5 References. setgid() §4.2.2. 
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4.2.4 Get User Name. 
Functions: getlogin(), cuserid () 
4.2.4.1 Synopsis. 


char *getlogin ( ) 
#include <stdio.h> 


char «cuserid (s) 
char *s; 


4.2.4.2 Description. These functions return a string giving a name of 
the user associated with the current process. The cuserid() function returns a 
name associated with the effective user ID of the process, and the getlogin() 
function returns the name associated by the login activity with the control ter- 
minal. 

The recommended procedure is either to call the cuserid() function, or to call 
getlogin() and, if it fails, to call the getpwuid() function with the value returned 
by the getuid() function. 

The getlogin() function returns a pointer to the user’s login name. The same 
user ID may be shared by several login names. Therefore, to ensure that the 
correct user database entry is found, the getlogin() function should be used with 
the getpwnam() function. 

If getlogin() returns a non-NULL pointer, that pointer is to the name the user 
logged in under, even if there are several login names with the same user ID. 

The cuserid() function generates a character representation of the login name 
of the owner of the current process. If s is not a NULL pointer, it is assumed 
that s points to an array of at least L_cuserid bytes; the representation is 
returned in this array. The symbolic constant L_cuserid is defined in 
<stdio.h>, and shall have a value greater than zero. 

4.2.4.3 Returns. The getlogin() function returns a pointer to a string 
containing the user’s login name, or a NULL pointer if the user’s login name 
cannot be found. 

The return value from getlogin() may point to static data and therefore may 
be overwritten by each call. 

If s is a NULL pointer, the result from cuserid() is generated in an area that 
may be static, the address of which is returned. If the login name cannot be 
found, cuserid() returns a NULL pointer. If s is not a NULL pointer, s is 
returned. If the login name cannot be found, the null character shall be placed 
at *s. The return value from cuserid() may point to static data and therefore 
may be overwritten by each call. 

The implementation of the cuserid() function may use the getpwnam() func- 
tion, so the results of a user’s call to either routine may be overwritten by a sub- 
sequent call to the other routine. 

4.2.4.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the cuserid() or getlogin() functions. Some errors 
may be detected under implementation-defined conditions. 
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4.2.45 References. getpwnam() §9.2.2, getpwuid() §9.2.2. 
4.3 Process Groups. 


4.3.1 Get Process Group ID. 
Function: getpgrp() 
4.3.1.1 Synopsis. 


#include <sys/types.h> 


pid_t getpgrp () 


4.3.1.2 Description. The getpgrp() function returns the process group ID 
of the calling process. 

4.3.1.3 Returns. See Description. 

4.3.1.4 Errors. The getpgrp() function is always successful, and no 
return value is reserved to indicate an error. 

4.3.1.5 References. setpgid() §4.3.3, setsid() §4.3.2, sigaction() §3.3.4. 


4.3.2 Create Session and Set Process Group ID. 
Function: setsid() 
4.3.2.1 Synopsis. 


#include <sys/types.h> 
pid_t setsid () 


4.3.2.2 Description. If the calling process is not a process group leader, 
the setsid() function shall create a new session. The calling process shall be the 
session leader of this new session, shall be the process group leader of a new 
process group, and shall have no controlling terminal. The process group ID of 
the calling process shall be set equal to the process ID of the calling process. 
The calling process shall be the only process in the new process group and the 
only process in the new session. 

4.3.2.3 Returns. Upon successful completion, the setsid() function 
returns the value of the process group ID of the calling process. 

4.3.2.4 Errors. If any of the following conditions occur, the setsid() func- 
tion shall return —1 and set errno to the corresponding value: 

[EPERM] The calling process is already a process group leader or the pro- 
cess group ID of a process other than the calling process 
matches the process ID of the calling process. 

4.3.2.5 References. exec §3.1.2, exit() §3.2.2, fork() §3.1.1, getpid() 
84.1.1, Rill() §3.3.2, setpgid() §4.3.3, sigaction() §3.3.4. 


4.3.3 Set Process Group ID for Job Control. 
Function: setpgid() 
4.3.3.1 Synopsis. 


#include <sys/types.h> 


int setpgid (pid, pgid) 
pid_t pid, pgid; 
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4.3.3.2 Description. 

If {_POSIX_JOB_CONTROL)} is defined: 

The setpgid() function is used to either join an existing process group 
or create a new process group within the session of the calling process. 
The process group ID of a session leader shall not change. Upon suc- 
cessful completion, the process group ID of the process with a process 
ID that matches pid shall be set to pgid. As a special case, if pid is 
zero, the process ID of the calling process shall be used. Also, if pgid is 
zero, the process ID of the indicated process shall be used. 

Otherwise: 

Either the implementation shall support the setpgid() function as 
described above or the setpgid() function shall fail. 
4.3.3.3 Returns. Upon successful completion, the setpgid() function 
returns a value of zero. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
4.3.3.4 Errors. If any of the following conditions occur, the setpgid() 
function shall return —1 and set errno to the corresponding value: 

[EACCES] The value of the pid argument matches the process ID of a child 
process of the calling process and the child process has success- 
fully executed one of the exec functions. 

[EINVAL] The value of the pgid argument is less than zero or is not a 
value supported by the implementation. 

[ENOSYS] The setpgid() function is not supported by this implementation. 

[EPERM] The process indicated by the pid argument is a session leader. 

The value of the pid argument is valid but matches the pro- 
cess ID of a child process of the calling process and the child 
process is not in the same session as the calling process. 

The value of the pgid argument does not match the process ID 
of the process indicated by the pid argument and there is no 
process with a process group ID that matches the value of the 
pgid argument in the same session as the calling process. 

[ESRCH] The value of the pid argument does not match the process ID of 
the calling process or of a child process of the calling process. 

4.3.3.5 References. getpgrp() §4.3.1, setsid() §4.3.2, tesetpgrp() §7.2.4, 
exec §3.1.2. 


4.4 System Identification. 


4.4.1 System Name. 
Function: uname() 
4.4.1.1 Synopsis. 


#include <sys/utsname.h> 


int uname (name) 
struct utsname *name; 
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4.4.1.2 Description. The uwname() function stores information identify- 
ing the current operating system in the structure pointed to by the argument 
name. 
The structure utsname is defined in the header <sys/utsname.h>, and con- 
tains at least the members shown in Table 4-1. 


Table 4-1. uname() Structure Members 


Member 
Name 


sysname Name of this implementation of the operating system. 


nodename Name of this node within an implementation-specified communi- 
cations network. 


Description 


release Current release level of this implementation. 
version Current version level of this release. 
machine Name of the hardware type that the system is running on. 


Each of these data items is a null-terminated character array. 

The format of each member is implementation-defined. The system documen- 
tation (see Documentation §2.2.1.2) shall specify the source and format of each 
member and may specify the range of values for each member. 

The inclusion of the nodename member in this structure does not imply that it 
is sufficient information for interfacing to communications networks. 

4.4.1.3 Returns. Upon successful completion, a non-negative value is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 

4.4.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the uname() function. Some errors may be 
detected under implementation-defined conditions. 


4.5 Time. 


4.5.1 Get System Time. 
Function: time() 
4.5.1.1 Synopsis. 


#include <time.h> 


time_t time (loc) 
time_t *tloc; 


4.5.1.2 Description. The time() function returns the value of time in 
seconds since the Epoch §2.3. 
The argument tloc points to an area where the return value is also stored. If 
tloc is a NULL pointer, no value is stored. 
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4.5.1.3 Returns. Upon successful completion, time() returns the value of 
time. Otherwise, a value of ((time_t) —1) is returned and errno is set to indicate 
the error. 

4.5.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the time() function. Some errors may be detected 
under implementation-defined conditions. 


4.5.2 Process Times. 
Function: times() 
4.5.2.1 Synopsis. 


#include <sys/times.h> 


clock_t times (buffer) 
struct tms «buffer; 


4.5.2.2 Description. The times() function shall fill the structure pointed 
to by buffer with time-accounting information. The type clock_t and the tms 
structure are defined in <sys/times.h>; the tms structure shall contain at least 
the following members: 


Member Member 


Fone Nae — Description 
clock_t tms_utime User CPU time. 
clock_t tms_stime System CPU time. 
clock_t tms_cutime User CPU time of terminated child processes. 
clock_t tms_cstime System CPU time of terminated child processes. 


All times are in {CLK_TCK}ths of a second. 

The times of a terminated child process are included in the tms_cutime and 
tms_cstime elements of the parent when a wait() or waitpid() function returns 
the process ID of this terminated child. See wait §3.2.1. If a child process has 
not waited for its terminated children, their times shall not be included in its 
times. 

The value tms_utime is the CPU time charged for the execution of user 
instructions. 

The value tms_stime is the CPU time charged for execution by the system on 
behalf of the process. 

The value tms_cutime is the sum of the tms_utimes and tms_cutimes of the 
child processes. 

The value tms_cstime is the sum of the tms_stimes and tms_cstimes of the 
child processes. 

4.5.2.3 Returns. Upon successful completion, times() shall return the 
elapsed real time, in {CLK_TCK}ths of a second, since an arbitrary point in the 
past (for example, system start-up time). This point does not change from one 
invocation of times() within the process to another. The return value may over- 
flow the possible range of type clock_t. If the times() function fails, a value of 
((clock_t) -1) is returned and errno is set to indicate the error. 
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4.5.2.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the times() function. Some errors may be 
detected under implementation-defined conditions. 

4.5.2.5 References. exec §3.1.2, fork() §3.1.1, time() §4.5.1, wait() §3.2.1. 


4.6 Environment Variables. 


4.6.1 Environment Access. 
Function: getenv() 
4.6.1.1 Synopsis. 


#include <stdlib.h> 


char *getenv (name) 
char «name; 


4.6.1.2 Description. The getenv() function searches the environment list 
(see Environment Description §2.7) for a string of the form name=value and 
returns a pointer to value if such a string is present. If the specified name can- 
not be found, a NULL pointer is returned. 

4.6.1.3 Returns. Upon successful completion, the getenv() function 
returns a pointer to a string containing the value for the specified name, or a 
NULL pointer if the specified name cannot be found. The return value from 
getenv() may point to static data and therefore may be overwritten by each call. 
Unsuccessful completion shall result in the return of a NULL pointer. 

4.6.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the getenv() function. Some errors may be 
detected under implementation-defined conditions. 

4.6.1.5 References. environ §3.1.2, Environment Description §2.7. 


4.7 Terminal Identification. 


4.7.1 Generate Terminal Pathname. 
Function: ctermid() 
4.7.1.1 Synopsis. 


#include <stdio.h> 


char «ctermid (s) 
char ‘*s; 


4.7.1.2 Description. The ctermid() function generates a string that, 
when used as a pathname, refers to the current controlling terminal for the 
current process. 

If the ctermid() function returns a pathname, access to the file is not 

guaranteed. 

4.7.1.3 Returns. If s is a NULL pointer, the string is generated in an 
area that may be static (and therefore may be overwritten by each call), the 
address of which is returned. Otherwise s is assumed to point to a character 
array of at least L_ctermid bytes; the string is placed in this array and the value 
of s is returned. The symbolic constant L_ctermid is defined in <stdio.h>, and 
shall have a value greater than zero. 
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The ctermid() function shall return an empty string if the pathname that 
would refer to the controlling terminal cannot be determined, of if the function 
is unsuccessful. 

4.7.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the ctermid() function. Some errors may be 
detected under implementation-defined conditions. 

4.7.1.5 References. tityname() §4.7.2. 


4.7.2 Determine Terminal Device Name. 
Functions: ttyname(), isatty() 
4.7.2.1 Synopsis. 


char *ttyname (fildes) 
int fildes; 


int isatty (fildes) 
int fildes; 


4.7.2.2 Description. The ttyname() function returns a pointer to a string 
containing a null-terminated pathname of the terminal associated with file 
descriptor fildes. 
The return value of ttyname() may point to static data that is overwritten by 
each call. 
The isatty() function returns 1 if fildes is a valid file descriptor associated 
with a terminal, zero otherwise. 
4.7.2.3. Returns. The tiyname() function returns a NULL pointer if fildes 
is not a valid file descriptor associated with a terminal or if the pathname can- 
not be determined. 
4.7.2.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the ttyname() or isatty() functions. Some errors 
may be detected under implementation-defined conditions. 


4.8 Configurable System Variables. 


4.8.1 Get Configurable System Variables. 
Function: sysconf() 
4.8.1.1 Synopsis. 


#include <unistd.h> 


long sysconf (name) 
int name; 


4.8.1.2 Description. The sysconf() function provides a method for the 
application to determine the current value of a configurable system limit or 
option (variable ). 

The name argument represents the system variable to be queried. The imple- 
mentation shall support all of the variables listed in Table 4-2 and may support 
others. The variables in Table 4-2 come from <limits.h> §2.9 or <unistd.h> 
§2.10 (or <time.h> from the C Standard for {CLK_TCK}), and the symbolic con- 
stants, defined in <unistd.h>, that are the corresponding values used for name. 
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Table 4-2. Configurable System Variables 


Variable ___name Value 
(ARG_MAX} { SC_ARG_MAX} 
{(CHILD_MAX} {_ SC_CHILD_MAX} 
(CLK_TCK} { 8C_CLK ‘TCK} 
{NGROUPS_MAX} {_ SC_NGROUPS_MAX} 
(OPEN_MAX} {_ SC_OPEN_MAX} 
{_POSIX_JOB_CONTROL} {_SC_JOB_CONTROL} 

{_ 


{_POSIX_SAVED_IDS} SC_SAVED_IDS} 
{_POSIX_VERSION} {_SC_VERSION} 


The value of {CLK_TCK} is permitted to be evaluated at run-time by the 
C Standard (and thus by this standard). The value returned by sysconf() for 
{_SC_CLK_TCK} shall be the same as that returned by {CLK_TCK}. 

4.8.1.3 Returns. If name is an invalid value, sysconf() shall return —1. If 
the variable corresponding to name is not defined on the system, sysconf() shall 
return —1 without changing the value of errno. 

Otherwise, the sysconf() function returns the current variable value on the 
system. The value returned shall not be more restrictive than the correspond- 
ing value described to the application when it was compiled with the 
implementation’s <limits.h> §2.9 or <unistd.h> §2.10. The value shall not 
change during the lifetime of the calling process. 

4.8.1.4 Errors. If any of the following conditions occur, the sysconf() 
function shall return —1 and set errno to the corresponding value: 
[EINVAL] The value of the name argument is invalid. 
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5. Files and Directories 


The functions in this section perform the operating system services dealing 
with the creation and removal of files and directories and the detection and 
modification of their characteristics. They also provide the primary methods a 
process will use to gain access to files and directories for subsequent I/O opera- 
tions (see Input and Output Primitives §6). 


5.1 Directories. 


5.1.1 Format of Directory Entries. The header <dirent.h> defines a 
structure and a defined type used by the directory routines. 

The internal format of directories is implementation-defined. 

The readdir() function returns a pointer to an object of type struct dirent that 
includes the member: 


Member Member 
Type Name _ 


char | | d_name Null-terminated filename 


Description 


The character array d_name is of unspecified size, but the number of bytes 
preceding the terminating null character shall not exceed {NAME_MAX}. 


5.1.2 Directory Operations. 
Functions: opendir(), readdir(), rewinddir(), closedir() 
5.1.2.1 Synopsis. 


#include <sys/types.h> 
#include <dirent.h> 


DIR *opendir (dirname) 
char *dirname; 


struct dirent «readdir (dirp) 
DIR *dirp; 


void rewinddir (dirp) 
DIR *dirp; 


int closedir (dirp) 
DIR «dirp; 
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5.1.2.2 Description. The type DIR, which is defined in the header 
<dirent.h> §5.1.1, represents a directory stream, which is an ordered sequence 
of all the directory entries in a particular directory. Directory entries represent 
files; files may be removed from a directory or added to a directory asynchro- 
nously to the operations described in this section. The type DIR may be imple- 
mented using a file descriptor. In that case, applications will only be able to 
open up to a total of {OPEN_MAX} files and directories; see open() §5.3.1. Ifa file 
descriptor is used, the FD_CLOEXEC flag shall be set on that file descriptor; see 
<fentl.h> §6.5.1. 

The opendir() function opens a directory stream corresponding to the direc- 
tory named by the dirname argument. The directory stream is positioned at the 
first entry. 

The readdir() function returns a pointer to a structure representing the direc- 
tory entry at the current position in the directory stream to which dirp refers, 
and positions the directory stream at the next entry. It returns a NULL pointer 
upon reaching the end of the directory stream. 

The readdir() function shall not return directory entries containing empty 
names. If entries for dot or dot-dot exist, one entry shall be returned for dot and 
one entry shall be returned for dot-dot; otherwise they shall not be returned. 

The pointer returned by readdir() points to data which may be overwritten by 
another call to readdir() on the same directory stream. This data shall not be 
overwritten by another call to readdir() on a different directory stream. 

The readdir() function may buffer several directory entries per actual read 
operation; the readdir() function shall mark for update the st_atime field of the 
directory each time the directory is actually read. 

The rewinddir() function resets the position of the directory stream to which 
dirp refers to the beginning of the directory. It also causes the directory stream 
to refer to the current state of the corresponding directory, as a call to opendir() 
would have done. It does not return a value. 

If a file is removed from or added to the directory after the most recent call to 
opendir() or rewinddir(), whether a subsequent call to readdir() returns an 
entry for that file is unspecified. 

The closedir() function closes the directory stream referred to by dirp and 
returns a value of zero if successful. Otherwise, it returns —1 indicating an 
error. Upon return, the value of dirp may no longer point to an accessible object 
of type DIR. If a file descriptor is used to implement type DIR, that file descrip- 
tor shall be closed. 

If the dirp argument passed to any of these functions does not refer to a 
currently-open directory stream, the effect is undefined. 

The result of using a directory stream after one of the exec family of functions 
is undefined. After a call to the fork() function, either the parent or the child 
(but not both) may continue processing the directory stream using readdir() or 
rewinddir() or both. If both the parent and child processes use these functions, 
the result is undefined. Either or both processes may use closedir(). 
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5.1.2.3 Returns. Upon successful completion, opendir() returns a pointer 
to an object of type DIR. Otherwise, a value of NULL is returned and errno is 
set to indicate the error. 

Upon successful completion, readdir() returns a pointer to an object of type 
struct dirent. When an error is encountered, a value of NULL is returned and 
errno is set to indicate the error. When the end of the directory is encountered, 
a value of NULL is returned and errno is not changed by this function call. 

Upon successful completion, closedir() returns a value of zero. Otherwise, a 
value of —-1 is returned and errno is set to indicate the error. 

5.1.2.4 Errors. If any of the following conditions occur, the opendir() 
function shall return a value of NULL and set errno to the corresponding value: 

[EACCES] Search permission is denied for any component of dirname or 
read permission is denied for dirname. 

[ENAMETOOLONG] 
The length of the dirname argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{_ POSIX_NO_TRUNC} is in effect. 

[ENOENT] The named directory does not exist. 

[ENOTDIR] A component of dirname is not a directory. 

For each of the following conditions, when the condition is detected, the open- 
dir() function shall return a value of NULL and set errno to the corresponding 
value: 

[EMFILE] Too many file descriptors are currently open for the process. 
[ENFILE] Too many file descriptors are currently open in the system. 

For each of the following conditions, when the condition is detected, the read- 
dir() function shall return a value of NULL and set errno to the corresponding 
value: 

[EBADF] The dirp argument does not refer to an open directory stream. 

For each of the following conditions, when the condition is detected, the 
closedir() function shall return —1 and set errno to the corresponding value: 

[EBADF] The dirp argument does not refer to an open directory stream. 
5.1.2.5 References. <dirent.h> §5.1.1. 


5.2 Working Directory. 


5.2.1 Change Current Working Directory. 
Function: chdir() 
5.2.1.1 Synopsis. 


int chdir (path) 
char «path; 


5.2.1.2 Description. The path argument points to the pathname of a 
directory. The chdir() function causes the named directory to become the 
current working directory, that is, the starting point for path searches of path- 
names not beginning with slash. 

If the chdir() function fails, the current working directory shall remain 
unchanged by this function call. 


5.2 Working Directory. 85 


IEEE 
Std 1003.1-1988 IEEE STANDARD PORTABLE OPERATING SYSTEM 


5.2.1.3 Returns. Upon successful completion, a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 
5.2.1.4 Errors. If any of the following conditions occur, the chdir() func- 
tion shall return —1 and set errno to the corresponding value: 
[EACCES] Search permission is denied for any component of the path- 
name. 
[ENAMETOOLONG] 
The path argument exceeds {PATH_MAX} in length, or a path- 
name component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 
[ENOTDIR] A component of the pathname is not a directory. 
[ENOENT] The named directory does not exist or path is an empty string. 
5.2.1.5 References. getcwd() §5.2.2. 


5.2.2 Working Directory Pathname. 
Function: getcwd() 
5.2.2.1 Synopsis. 


char *getcwd (buf, size) 
char «buf; 
int size; 


5.2.2.2 Description. The getcwd() function copies an absolute pathname 
of the current working directory to the character array pointed to by the argu- 
ment buf and returns a pointer to the result. The size argument is the size in 
bytes of the character array pointed to by the buf argument. If buf is a NULL 
pointer, the behavior of getcwd() is undefined. 
5.2.2.3 Returns. If successful, the buf argument is returned. A NULL 
pointer is returned if an error occurs and the variable errno is set to indicate the 
error. The contents of buf after an error is undefined. 
5.2.2.4 Errors. If any of the following conditions occur, the getcwd() 
function shall return a value of NULL and set errno to the corresponding value: 
[EINVAL] The size argument is less than or equal to zero. 
[ERANGE] The size argument is greater than zero, but is smaller than the 
length of the pathname plus 1. 
For each of the following conditions, if the condition is detected, the getcwd() 
function shall return a value of NULL and set errno to the corresponding value: 
[EACCES] Read or search permission was denied for a component of the 
pathname. 
5.2.2.5 References. chdir() §5.2.1. 
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5.3 General File Creation. 


5.3.1 Open a File. 
Function: open() 
5.3.1.1 Synopsis. 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 


int open (path, oflag,...) 
char «path; 
int oflag; 


5.3.1.2 Description. The open() function establishes the connection 
between a file and a file descriptor. It creates an open file description that 
refers to a file and a file descriptor that refers to that open file description. The 
file descriptor is used by other I/O functions to refer to that file. The path argu- 
ment points to a pathname naming a file. 

The open() function shall return a file descriptor for the named file which is 
the lowest file descriptor not currently open for that process. The open file 
description is new, and therefore the file descriptor does not share it with any 
other process in the system. The file offset shall be set to the beginning of the 
file. The file status flags and file access modes of the open file description shall 
be set according to the value of oflag. The value of oflag is the bitwise inclusive 
OR of values from the following list. See <fentl.h> §6.5.1 for the definitions of 
the symbolic constants. Applications shall specify exactly one of the first three 
values (file access modes) below in the value of oflag: 

O_RDONLY Open for reading only. 

O_WRONLY _ Open for writing only. 

O_RDWR Open for reading and writing. The result is undefined if this 
flag is applied to a FIFO. 

Any combination of the remaining flags may be specified in the value of oflag: 

O_APPEND If set, the file offset shall be set to the end of the file prior to 
each write. 

O_CREAT This option requires a third argument, mode, which is of type 
mode_t. If the file exists, this flag has no effect, except as 
noted under O_EXCL, below. Otherwise, the file is created; 
the file’s user ID shall be set to the process’s effective user ID; 
the file’s group ID shall be set to the group ID of the directory 
in which the file is being created or to the process’s effective 
group ID. The file permission bits (see <sys/stat.h> §5.6.1) 
shall be set to the value of mode except those set in the 
process’s file mode creation mask (see umask() §5.3.3). When 
bits in mode other than the file permission bits are set, the 
effect is implementation-defined. The mode argument does 
not affect whether the file is opened for reading, for writing, 
or for both. 
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If O_LEXCL and O_CREAT are set, open() shall fail if the file 
exists. The check for the existence of the file and the creation 
of the file if it does not exist shall be atomic with respect to 
other processes executing open() naming the same filename 
in the same directory with O_EXCL and O_CREAT set. If 
O_EXCL is set and O_CREAT is not set, the result is 
implementation-defined. 

If set, and path identifies a terminal device, the open() func- 
tion shall not cause the terminal device to become the control- 
ling terminal for the process (see The Controlling Termi- 
nal §7.1.1.3). 


(1) When opening a FIFO with O_RDONLY or O_WRONLY 
set: 
(a) If O. NONBLOCK is set: 
An open() for reading-only shall return without delay. 
An open() for writing-only shall return an error if no 
process currently has the file open for reading. 
(b) If O.NONBLOCK is clear: 
An open() for reading-only shall block until a process 
opens the file for writing. An open() for writing-only 
shall block until a process opens the file for reading. 
(2) When opening a block special or character special file 
that supports nonblocking opens: 
(a) If O.NONBLOCK is set: 
The open() shall return without waiting for the device 
to be ready or available. Subsequent behavior of the 
device is device-specific. 
(b) If O.NONBLOCK is clear: 
The open() shall wait until the device is ready or avail- 
able before returning. 
(3) Otherwise, the behavior of O_NONBLOCK is unspeci- 
fied. 
If the file exists and is a regular file, and the file is success- 
fully opened O_RDWR or O_WRONLY, it shall be truncated to 
zero length and the mode and owner shall be unchanged by 
this function call. O_TRUNC shall have no effect on FIFO spe- 
cial files or directories. Its effect on other file types is 
implementation-defined. The result of using O_TRUNC with 
O_RDONLY is undefined. 


If O_CREAT is set and the file did not previously exist, upon successful com- 
pletion, the open() function shall mark for update the st_atime, st_ctime, and 
st_mtime fields of the file and the st_ctime and st_mtime fields of the parent 


directory. 


If O_TRUNC is set and the file did previously exist, upon successful comple- 
tion, the open() function shall mark for update the st_ctime and st_mtime fields 


of the file. 
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5.3.1.8 Returns. Upon successful completion, the function shall open the 
file and return a non-negative integer representing the lowest numbered 
unused file descriptor. Otherwise, it shall return —1 and shall set errno to indi- 
cate the error. No files shall be created or modified if the function returns —1. 

5.3.1.4 Errors. If any of the following conditions occur, the open() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path prefix, 
or the file exists and the permissions specified by oflag are 
denied, or the file does not exist and write permission is denied 
for the parent directory of the file to be created, or O_TRUNC is 
specified and write permission is denied. 

[EEXIST] O_CREAT and O_EXCL are set, and the named file exists. 

[EINTR] The open() operation was interrupted by a signal. 

[EISDIR] The named file is a directory and the oflag argument specifies 
write or read/write access. 

[EMFILE] Too many file descriptors are currently in use by this process. 

[ENAMETOOLONG] 

The length of the path string exceeds {PATH_MAX}, or a path- 
name component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 

[ENFILE] Too many files are currently open in the system. 

[ENOENT] O_CREAT is not set and the named file does not exist; or 
O_CREAT is set and either the path prefix does not exist or the 
path argument points to an empty string. 

[ENOSPC] The directory or file system which would contain the new file 
cannot be extended. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is 
set, and no process has the file open for reading. 

[EROFS] The named file resides on a read-only file system and either 
O_WRONLY, O_RDWR, O_CREAT (if the file does not exist), or 
O_TRUNC is set in the oflag argument. 

5.3.1.5 References. close() §6.3.1, creat() §5.3.2, dup() §6.2.1, exec §3.1.2, 
fentl() §6.5.2, <fentl.h> §6.5.1, lseek() §6.5.3, read() §6.4.1, <signal.h> §3.3.1, 
stat() §5.6.2, <sys/stat.h> §5.6.1, write() §6.4.2, umask() §5.3.3, Signal Effects 
on Other Functions §3.3.1.4. 
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5.3.2 Create a New File or Rewrite an Existing One. 


Function: creat() 
5.3.2.1 Synopsis. 


#include <sys/types.h> 


#include <sys/stat.h> 
#include <fcntl.h> 


int creat (path, mode) 
char * path; 
mode_t mode; 


5.3.2.2 Description. The function call: 


creat (path, mode); 


is equivalent to: 


open (path, O_WRONLY | O_CREAT | O_TRUNC, mode); 
5.3.2.3 References. open() §5.3.1, <sys/stat.h> §5.6.1. 


5.3.3 Set File Creation Mask. 


Function: umask() 
5.3.3.1 Synopsis. 


#include <sys/types.h> 


#include <sys/stat.h> 


mode_t umask (cmask) 


mode_t cmask; 


5.3.3.2 Description. The uwmask() routine sets the process’s file mode 
creation mask to cmask and returns the previous value of the mask. Only the 
file permission bits (see <sys/stat.h> §5.6.1) of cmask are used; the meaning of 
the other bits is implementation-defined. 

The process’s file mode creation mask is used during open(), creat(), mkdir(), 
and mkfifo() calls to turn off permission bits in the mode argument supplied. 
Bit positions that are set in cmask are cleared in the mode of the created file. 

5.3.3.3 Returns. The previous value of the file mode creation mask is 


returned. 


5.3.3.4 Errors. The wmask() function is always successful, and no return 
value is reserved to indicate an error. 

5.3.3.5 References. chmod() §5.6.4, creat() §5.3.2, mkdir() §5.4.1, 
mkfifo() §5.4.2, open() §5.3.1, <sys/stat.h> §5.6.1. 


5.3.4 Link to a File. 
Function: link() 
5.3.4.1 Synopsis. 


int link (path1, path2) 
char *path1, «path2; 
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5.3.4.2 Description. The argument path! points to a pathname naming 
an existing file. The argument path2 points to a pathname naming the new 
directory entry to be created. Implementations may support linking of files 
across file systems. The Jink() function shall atomically create a new link for 
the existing file and increment the link count of the file by one. 

If the link() function fails, no link shall be created and the link count of the 
file shall remain unchanged by this function call. 

The path1 argument shall not name a directory unless the user has appropri- 
ate privileges and the implementation supports using Jink() on directories. 

The implementation may require that the calling process has permission to 
access the existing file. 

Upon successful completion, the dink() function shall mark for update the 
st_ctime field of the file. Also, the st_ctime and st_mtime fields of the directory 
that contains the new entry are marked for update. 

5.3.4.3 Returns. Upon successful completion, link() shall return a value 
of zero. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 

5.3.4.4 Errors. If any of the following conditions occur, the link() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] A component of either path prefix denies search permission, or 
the requested link requires writing in a directory with a mode 
that denies write permission, or the calling process does not 
have permission to access the existing file and this is required 
by the implementation. 

[EEXIST] The link named by path2 exists. 

[EMLINK] The number of links to the file named by path1I would exceed 
{LINK_MAX}. 

[ENAMETOOLONG] 

The length of the path1 or path2 string exceeds {PATH_MAX}, or 
a pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOENT] A component of either path prefix does not exist; the file named 
by path1 does not exist; or either path1 or path2 points to an 
empty string. 

[ENOSPC] The directory that would contain the link cannot be extended. 

[ENOTDIR] A component of either path prefix is not a directory. 

[EPERM] The file named by path1 is a directory and either the calling 
process does not have appropriate privileges, or the implemen- 
tation prohibits using link() on directories. 

[EROFS] The requested link requires writing in a directory on a read- 
only file system. 

[EXDEV] The link named by path2 and the file named by path are on 
different file systems and the implementation does not support 
links between file systems. 

5.3.4.5 References. rename() §5.5.3, unlink() §5.5.1. 
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5.4 Special File Creation. 


5.4.1 Make a Directory. 
Function: mkdir() 
5.4.1.1 Synopsis. 


#include <sys/types.h> 
#include <sys/stat.h> 


int mkdir (path, mode) 
char *path; 
mode_t mode; 


5.4.1.2 Description. The mkdir() routine creates a new directory with 
name path. The file permission bits of the new directory are initialized from 
mode. The file permission bits of the mode argument are modified by the 
process’s file creation mask (see umask() §5.3.3). When bits in mode other than 
the file permission bits are set, the meaning of these additional bits is 
implementation-defined. 

The directory’s owner ID is set to the process’s effective user ID. The 
directory’s group ID shall be set to the group ID of the directory in which the 
directory is being created or to the process’s effective group ID. 

The newly-created directory shall be an empty directory. 

Upon successful completion, the mkdir() function shall mark for update the 
st_atime, st_ctime, and st_mtime fields of the directory. Also, the st_ctime and 
st_mtime fields of the directory that contains the new entry are marked for 
update. 

5.4.1.3 Returns. A return value of zero indicates success. A return value 
of —1 indicates that an error has occurred and an error code is stored in errno. 
No directory shall be created if the return value is —1. 

5.4.1.4 Errors. If any of the following conditions occur, the mkdir() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path prefix, 
or write permission is denied on the parent directory of the 
directory to be created. 

[EEXIST] The named file exists. 

[EMLINK] The link count of the parent directory would exceed 
{LINK_MAX}. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 

[ENOENT] A component of the path prefix does not exist or the path argu- 
ment points to an empty string. 

[ENOSPC] The file system does not contain enough space to hold the con- 
tents of the new directory or to extend the parent directory of 
the new directory. 
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[ENOTDIR] A component of the path prefix is not a directory. 
[EROFS] The parent directory of the directory being created resides on a 
read-only file system. 
5.4.1.5 References. chmod() §5.6.4, stat() §5.6.2, <sys/stat.h> §5.6.1, 
umask() §5.3.3. 


5.4.2 Make a FIFO Special File. 
Function: mkfifo() 
5.4.2.1 Synopsis. 


#include <sys/types.h> 
#include <sys/stat.h> 


int mkfifo (path, mode) 
char «path; 
mode_t mode; 


5.4.2.2 Description. The mAfifo() routine creates a new FIFO special file 
named by the pathname pointed to by path. The file permission bits of the new 
FIFO are initialized from mode. The file permission bits of the mode argument 
are modified by the process’s file creation mask (see umask() §5.3.3). When bits 
in mode other than the file permission bits are set, the effect is 
implementation-defined. 

The FIFO’s owner ID shall be set to the process’s effective user ID. The FIFO’s 
group ID shall be set to the group ID of the directory in which the FIFO is being 
created or to the process’s effective group ID. 

Upon successful completion, the m&fifo() function shall mark for update the 
st_atime, st_ctime, and st_mtime fields of the file. Also, the st_ctime and 
st_mtime fields of the directory that contains the new entry are marked for 
update. 

5.4.2.3 Returns. Upon successful completion a value of zero is returned. 
Otherwise, a value of —1 is returned, no FIFO is created, and errno is set to indi- 
cate the error. 
5.4.2.4 Errors. If any of the following conditions occur, the mkfifo() func- 
tion shall return —1 and set errno to the corresponding value: 
[EACCES] A component of the path prefix denies search permission. 
[EEXIST] The named file already exists. 
[ENAMETOOLONG] 
The length of the path string exceeds {PATH_MAX}, or a path- 
name component is longer than {NAME _MAX} while 
{_POSIX_NO_TRUNC]} is in effect. 
[ENOENT] A component of the path prefix does not exist or the path argu- 
ment points to an empty string. 
[ENOSPC] The directory that would contain the new file cannot be 
extended or the file system is out of file allocation resources. 
[ENOTDIR] A component of the path prefix is not a directory. 
[EROFS] The named file resides on a read-only file system. 
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5.4.2.5 References. chmod() §5.6.4, exec §3.1.2, pipe() §6.1.1, stat() 
§5.6.2, <sys/stat.h> §5.6.1, umask() §5.3.3. 


5.5 File Removal. 


5.5.1 Remove Directory Entries. 
Function: unlink() 
5.5.1.1 Synopsis. 


int unlink (path) 
char *path; 


5.5.1.2 Description. The unlink() function shall remove the link named 
by the pathname pointed to by path and decrement the link count of the file 
referenced by the link. 

When the file’s link count becomes zero and no process has the file open, the 
space occupied by the file shall be freed and the file shall no longer be accessible. 
If one or more processes have the file open when the last link is removed, the 
link shall be removed before unlink() returns, but the removal of the file con- 
tents shall be postponed until all references to the file have been closed. 

The path argument shall not name a directory unless the process has 
appropriate privileges and the implementation supports using wnlink() on direc- 
tories. Applications should use rmdir() to remove a directory. 

Upon successful completion, the unlink() function shall mark for update the 
st_ctime and st_mtime fields of the parent directory. Also, if the file’s link count 
is not zero, the st_ctime field of the file shall be marked for update. 

5.5.1.3 Returns. Upon successful completion, a value of zero shall be 
returned. Otherwise, a value of —1 shall be returned and errno shall be set to 
indicate the error. If —1 is returned, the named file shall not be changed by this 
function call. 

5.5.1.4 Errors. If any of the following conditions occur, the unlink() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix, 
or write permission is denied on the directory containing the 
link to be removed. 

[EBUSY] The directory named by the path argument cannot be unlinked 
because it is being used by the system or another process and 
the implementation considers this to be an error. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The file named by path is a directory and either the calling pro- 
cess does not have appropriate privileges, or the implementa- 
tion prohibits using unlink() on directories. 
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[EROFS] The directory entry to be unlinked resides on a read-only file 
system. 
5.5.1.5 References. close() §6.3.1, link() §5.3.4, open() §5.3.1, rename() 
§5.5.3, rmdir( §5.5.2. 


5.5.2 Remove a Directory. 
Function: rmdir() 
5.5.2.1 Synopsis. 


int rmdir (path) 
char «path; 


5.5.2.2 Description. The rmdir() function removes a directory whose 
name is given by path. The directory shall be removed only if it is an empty 
directory. 

If the directory is the root directory or the current working directory of any 
process, the effect of this function is implementation-defined. 

If the directory’s link count becomes zero and no process has the directory 
open, the space occupied by the directory shall be freed and the directory shall 
no longer be accessible. If one or more processes have the directory open when 
the last link is removed, the dot and dot-dot entries, if present, are removed 
before rmdir() returns and no new entries may be created in the directory, but 
the directory is not removed until all references to the directory have been 
closed. 

Upon successful completion, the rmdir() function shall mark for update the 
st_ctime and st_mtime fields of the parent directory. 

5.5.2.3 Returns. A return value of zero indicates success. A return value 
of —1 indicates that an error has occurred and an error code has been stored in 
errno. 

5.5.2.4 Errors. If any of the following conditions occur, the rmdir() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path or write 
permission is denied on the parent directory of the directory to 
be removed. 

[EBUSY] The directory named by the path argument cannot be removed 
because it is being used by another process and the implemen- 
tation considers this to be an error. 

[EEXIST] or [ENOTEMPTY] 

The path argument names a directory that is not an empty 
directory. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 

[ENOENT] The path argument names a non-existent directory or points to 

an empty string. 
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[ENOTDIR] A component of the path is not a directory. 
[EROFS] The directory entry to be removed resides on a read-only file 


system. 
5.5.2.5 References. mkdir() §5.4.1, unlink() §5.5.1. 


5.5.3 Rename a File. 
Function: rename() 
5.5.3.1 Synopsis. 


int rename (old, new) 
char «old; 
char *new; 


5.5.3.2 Description. The rename() function changes the name of a file. 
The old argument points to the pathname of the file to be renamed. The new 
argument points to the new pathname of the file. 

If the old argument and the new argument both refer to links to the same 
existing file, the rename() function shall return successfully and perform no 
other action. 

If the old argument points to the pathname of a file that is not a directory, the 
new argument shall not point to the pathname of a directory. If the link named 
by the new argument exists, it shall be removed and old renamed to new. In 
this case, a link named new shall exist throughout the renaming operation and 
shall refer either to the file referred to by new or old before the operation began. 
Write access permission is required for both the directory containing old and the 
directory containing new. 

If the old argument points to the pathname of a directory, the new argument 
shall not point to the pathname of a file that is not a directory. If the directory 
named by the new argument exists, it shall be removed and old renamed to new. 
In this case, a link named new shall exist throughout the renaming operation 
and shall refer either to the file referred to by new or old before the operation 
began. Thus, if new names an existing directory, it shall be required to be an 
empty directory. 

The new pathname shall not contain a path prefix that names old. Write 
access permission is required for the directory containing old and the directory 
containing new. If the old argument points to the pathname of a directory, 
write access permission may be required for the directory named by old, and, if 
it exists, the directory named by new. 

If the link named by the new argument exists and the file’s link count 
becomes zero when it is removed and no process has the file open, the space 
occupied by the file shall be freed and the file shall no longer be accessible. If 
one or more processes have the file open when the last link is removed, the link 
shall be removed before rename() returns, but the removal of the file contents 
shall be postponed until all references to the file have been closed. 

Upon successful completion, the rename() function shall mark for update the 
st_ctime and st_mtime fields of the parent directory of each file. 
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5.5.3.3 Returns. A return value of zero indicates success. A return value 
of —1 indicates that an error has occurred and an error code has been stored in 
errno. 

5.5.3.4 Errors. If any of the following conditions occur, the rename() 
function shall return —1 and set errno to the corresponding value: 

[EACCES]} A component of either path prefix denies search permission; or 
one of the directories containing old or new denies write per- 
missions; or, write permission is required and is denied for a 
directory pointed to by the old or new arguments. 

[EBUSY] The directory named by old or new cannot be renamed because 
it is being used by the system or another process and the imple- 
mentation considers this to be an error. 

[EEXIST] or [ENOTEMPTY] 

The link named by new is a directory containing entries other 
than dot and dot-dot. 

[EINVAL] The new directory pathname contains a path prefix that names 
the old directory. 

[EISDIR] The new argument points to a directory and the o/d argument 
points to a file that is not a directory. 

[ENAMETOOLONG] 

The length of the old or new argument exceeds {PATH_MAX}, or 
a pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOENT] The link named by the o/d argument does not exist or either old 
or new points to an empty string. 

[ENOSPC] The directory that would contain new cannot be extended. 

[ENOTDIR] A component of either path prefix is not a directory; or the old 
argument names a directory and the new argument names a 
nondirectory file. 

[EROFS] The requested operation requires writing in a directory on a 
read-only file system. 

[EXDEV] The links named by new and old are on different file systems 
and the implementation does not support links between file sys- 
tems. 

5.5.3.0 References. link() §5.3.4, rmdir() §5.5.2, unlink() $5.5.1. 


5.6 File Characteristics. 


5.6.1 File Characteristics: Header and Data Structure. The header 
<sys/stat.h> defines the structure stat, which includes the members shown in 
Table 5-1, returned by the functions stat() and fstat(). 

All of the described members shall appear in the stat structure. The structure 
members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and 
st_mtime shall have meaningful values for all file types defined in this standard. 
The value of the member st_nlink shall be set to the number of links to the file. 
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Member Member 


Type Name 
mode_t st_mode 
ino_t st_ino 
dev_t st_dev 


nlink_t st_nlink 


uid_t st_uid 
gid_t st_gid 
off_t st_size 
time_t st_atime 
time_t st_mtime 
time_t st_ctime . 
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Table 5-1. stat Structure 


Description 


File mode (see <sys/stat.h> File Modes §5.6.1.2). 
File serial number. 

ID of device containing this file. 

File serial number and device ID taken together 
uniquely identify the file within the system. 


Number of links. 

User ID of the file’s owner. 

Group ID of the file’s group. 

For regular files, the file size in bytes. For other file 
types, the use of this field is unspecified. 

Time of last access. 

Time of last data modification. 

Time of last file status change. 


5.6.1.1 <sys/stat.h> File Types. The following macros shall test whether 
a file is of the specified type. The value m supplied to the macros is the value of 
st_mode from a sfat structure. The macro evaluates to a non-zero value if the 
test is true, zero if the test is false. 
S_ISDIR(m) Test macro for directory file. 
S_ISCHR(m) Test macro for character special file. 
S_ISBLK(m) Test macro for block special file. 
S_ISREG(m) Test macro for regular file. 
S_ISFIFO(m) Test macro for pipe or FIFO special file. 
5.6.1.2 <sys/stat.h> File Modes. The file modes portion of values of type 
mode_t, such as the st_mode value, are bit-encoded with the following masks 


and bits: 


S_IRWXU __ Read, write, search (if a directory), or execute (otherwise) per- 
missions mask for the file owner class. 
S_IRUSR Read permission bit for the file owner class. 
S.IWUSR Write permission bit for the file owner class. 
S_IXUSR Search (if a directory) or execute (otherwise) 


permissions bit for the file owner class. 


S_IRWXG Read, write, search (if a directory), or execute (otherwise) per- 
missions mask for the file group class. 
S_IRGRP Read permission bit for the file group class. 
S_IWGRP Write permission bit for the file group class. 
S_IXGRP Search (if a directory) or execute (otherwise) 


permissions bit for the file group class. 


S_IRWXO Read, write, search (if a directory), or execute (otherwise) per- 
missions mask for the file other class. 
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S_IROTH _ Read permission bit for the file other class. 

S_IWOTH Write permission bit for the file other class. 

S_IXOTH Search (if a directory) or execute (otherwise) 
permissions bit for the file other class. 

S_ISUID Set user ID on execution. The process’s effective user ID shall 
be set to that of the owner of the file when the file is run as a 
program (see exec). On a regular file, this bit should be cleared 
on any write. 

S_ISGID Set group ID on execution. Set effective group ID on the process 
to the file’s group when the file is run as a program (see exec). 
On a regular file, this bit should be cleared on any write. 

The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, 
S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, and S_ISGID shall be unique. 
S_IRWXU shall be the bitwise inclusive OR of S_ IRUSR, S_IWUSR, and S_IXUSR. 
S_IRWXG shall be the bitwise inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP. 
S_IRWXO shall be the bitwise inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH. 
Implementations may OR other implementation-defined bits into S_IRWXU, 
S_IRWXG, and S_IRWXO, but they shall not overlap any of the other bits defined 
in this standard. The file permission bits are defined to be those corresponding 
to the bitwise inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO. 

5.6.1.3 <sys/stat.h> Time Entries. The time-related fields of struct stat 
are as follows: 


st_atime Accessed file data, for example read(). 
st_mtime Modified file data, for example write(). 
st_ctime Changed file status, for example chmod (). 


These times are updated as described by file times update §2.4. 

All the functions in this standard that change these fields directly describe 
those changes in the context of the functions’ definitions. Other functions that 
directly change st_atime, st_mtime, or st_ctime shall be implementation-defined. 

Times are given in seconds since the Epoch §2.3. 

5.6.1.4 References. chmod() §5.6.4, chown() §5.6.5, creat() §5.3.2, exec 
§3.1.2, link() §5.3.4, mkdir() §5.4.1, mkfifo() §5.4.2, pipe() §6.1.1, read() §6.4.1, 
unlink() §5.5.1, utime() §5.6.6, write() §6.4.2, remove() (C Standard). 


5.6.2 Get File Status. 
Functions: stat(), fstat() 
5.6.2.1 Synopsis. 


#include <sys/types.h> 
#include <sys/stat.h> 


int stat (path, buf) 
char «path; 

struct stat «buf; 

int fstat (fildes, buf) 
int fildes; 

struct stat «buf; 
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5.6.2.2 Description. The path argument points to a pathname naming a 
file. Read, write or execute permission for the named file is not required, but all 
directories listed in the pathname leading to the file must be searchable. The 
stat() function obtains information about the named file and writes it to the 
area pointed to by the buf argument. 

Similarly, the fstat() function obtains information about an open file known 
by the file descriptor /fildes. 

An implementation that provides additional or alternate file access control 
mechanisms may, under implementation-defined conditions, cause the stat() 
and fstat() functions to fail. In particular, the system may deny the existence of 
the file specified by path. 

Both functions update any time-related fields as described in file times 
update §2.4 before writing into the stat structure. 

The buf is taken to be a pointer to a stat structure, as defined in the header 
<sys/stat.h> §5.6.1, into which information is placed concerning the file. 

5.6.2.3 Returns. Upon successful completion a value of zero shall be 
returned. Otherwise, a value of —1 shall be returned and errno shall be set to 
indicate the error. 

5.6.2.4 Errors. If any of the following conditions occur, the stat() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix. 

[ENAMETOOLONG] 
The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

If any of the following conditions occur, the fstat() function shall return —1 
and set errno to the corresponding value: 

[EBADF] The fildes argument is not a valid file descriptor. 

5.6.2.5 References. creat() §5.3.2, dup() §6.2.1, fentlQ §6.5.2, open() 
§5.3.1, pipe() §6.1.1, <sys/stat.h> §5.6.1. 


5.6.3 File Accessibility. 
Function: access() 
5.6.3.1 Synopsis. 


#include <unistd.h> 


int access (path, amode) 
char «path; 
int amode; 


5.6.3.2 Description. The access() function checks the accessibility of the 
file named by the pathname pointed to by the path argument for the file access 
permissions indicated by amode, using the real user ID in place of the effective 
user ID and the real group ID in place of the effective group ID. 
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The value of amode is either the bitwise inclusive OR of the access permis- 
sions to be checked (R_OK, W_OK, and X_OK) or the existence test, F_LOK. See 
Symbolic Constants for the access() Function $2.10.1 for the description of 
these symbolic constants. 

If any access permission is to be checked, each shall be checked individually, 
as described in file access permissions §2.4. If the process has appropriate 
privileges, an implementation may indicate success for X_OK even if none of the 
execute file permission bits are set. 

5.6.3.3 Returns. If the requested access is permitted, a value of zero 
shall be returned. Otherwise, a value of —1 shall be returned and errno shall be 
set to indicate the error. 
5.6.3.4 Errors. If any of the following conditions occur, the access() func- 
tion shall return —-1 and set errno to the corresponding value: 
[EACCES] The permissions specified by amode are denied, or search per- 
mission is denied on a component of the path prefix. 
[ENAMETOOLONG] 
The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 
[ENOENT] The path argument points to an empty string or to the name of 
a file that does not exist. 
[ENOTDIR] A component of the path prefix is not a directory. 
[EROFS] Write access was requested for a file residing on a read-only file 
system. 

For each of the following conditions, if the condition is detected, the access() 

function shall return —1 and set errno to the corresponding value: 
[EINVAL] An invalid value was specified for amode. 
5.6.3.5 References. chmod() §5.6.4, stat() §5.6.2, <unistd.h> §2.10. 


5.6.4 Change File Modes. 
Function: chmod() 
5.6.4.1 Synopsis. 


#include <sys/types.h> 
#include <sys/stat.h> 


int chmod (path, mode) 
char «path; 
mode_t mode; 


5.6.4.2 Description. The path argument shall point to a pathname nam- 
ing a file. If the effective user ID of the calling process matches the file owner or 
the calling process has appropriate privileges, the chmod() function shall set the 
S_ISUID, S_ISGID, and the file permission bits, as described in <sys/stat.h> 
§5.6.1, of the named file from the corresponding bits in the mode argument. 
These bits define access permissions for the user associated with the file, the 
group associated with the file, and all others, as described in file access per- 
missions §2.4. Additional implementation-defined restrictions may cause the 
S_ISUID and S_ISGID bits in mode to be ignored. 
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If the calling process does not have appropriate privileges, and if the group ID 
of the file does not match the effective group ID or one of the supplementary 
group IDs, and if the file is a regular file, bit S_ISGID (set group ID on execution) 
in the file’s mode shall be cleared upon successful return from chmod (). 

The effect on file descriptors for files open at the time of the chmod () function 
is implementation-defined. 

Upon successful completion, the chmod() function shall mark for update the 
st_ctime field of the file. 

5.6.4.3. Returns. Upon successful completion, the function shall return a 
value of zero. Otherwise, a value of —1 shall be returned and errno shall be set 
to indicate the error. If —1 is returned, no change to the file mode shall have 
occurred. 

5.6.4.4 Errors. If any of the following conditions occur, the chmod() 
function shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path prefix. 

[ENAMETOOLONG] 
The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[EPERM] The effective user ID does not match the owner of the file and 
the calling process does not have the appropriate privileges. 

[EROFS] The named file resides on a read-only file system. 

5.6.4.5 References. chown() §5.6.5, mkdir() §5.4.1, mkfifoQ §5.4.2, 
stat() §5.6.2, <sys/stat.h> §5.6.1. 


5.6.5 Change Owner and Group of a File. 
Function: chown() 
5.6.5.1 Synopsis. 


#include <sys/types.h> 


int chown (path, owner, group) 
char «path; 

uid_t owner; 

gid_t group; 


5.6.5.2 Description. The path argument points to a pathname naming a 
file. The user ID and group ID of the named file are set to the numeric values 
contained in owner and group respectively. 

Only processes with an effective user ID equal to the user ID of the file or with 
appropriate privileges may change the ownership of a file. If 
{_POSIX_CHOWN_RESTRICTED} is in effect for path: 

(1) Changing the owner is restricted to processes with appropriate privileges. 
(2) Changing the group is permitted to a process with an effective user ID 
equal to the user ID of the file, but without appropriate privileges, if and only 
if owner is equal to the file’s user ID and group is equal either to the calling 


102 Files and Directories 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


process’s effective group ID or to one of its supplementary group IDs. 

If the path argument refers to a regular file, the set-user-ID (S_ISUID) and 
set-group-ID (S_ISGID) bits of the file mode shall be cleared upon successful 
return from chown(), unless the call is made by a process with appropriate 
privileges, in which case it is implementation-defined whether those bits are 
altered. If the chown() function is successfully invoked on a file that is not a 
regular file, these bits may be cleared. These bits are defined in <sys/stat.h> 
Soyoule 

Upon successful completion, the chown() function shall mark for update the 
st_ctime field of the file. 

5.6.5.3 Returns. Upon successful completion, a value of zero shall be 
returned. Otherwise, a value of —1 shall be returned and errno shall be set to 
indicate the error. If —1 is returned, no change shall be made in the owner and 
group of the file. 

5.6.5.4 Errors. If any of the following conditions occur, the chown() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied on a component of the path prefix. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{_POSIX_NO_TRUNC} is in effect. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[EPERM] The effective user ID does not match the owner of the file or the 
calling process does not have appropriate privileges and 
{_POSIX_CHOWN_RESTRICTED} indicates that such privilege is 
required. 

[EROFS] The named file resides on a read-only file system. 

For each of the following conditions, if the condition is detected, the chown() 
function shall return —1 and set errno to the corresponding value: 

[EINVAL] The owner or group ID supplied is invalid and not supported by 
the implementation. 

5.6.5.5 References. chmod() §5.6.4, <sys/stat.h> §5.6.1. 


5.6.6 Set File Access and Modification Times. 
Function: utime() 
5.6.6.1 Synopsis. 


#include <sys/types.h> 
#include <utime.h> 


int utime (path, times) 
char *path; 
struct utimbuf *times; 
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5.6.6.2 Description. The argument path points to a pathname naming a 
file. The uwtime() function sets the access and modification times of the named 
file. 

If the times argument is NULL, the access and modification times of the file 
are set to the current time. The effective user ID of the process must match the 
owner of the file, or the process must have write permission to the file or 
appropriate privileges, to use the utime() function in this manner. 

If the times argument is not NULL, it is interpreted as a pointer to a utimbuf 
structure and the access and modification times are set to the values contained 
in the designated structure. Only the owner of the file and processes with 
appropriate privileges shall be permitted to use the wtime() function in this way. 

The utimbuf structure is defined by the header <utime.h>, and includes the 
following members: 


Member Member 


ne Neways Description 
time_t actime Access time 
time_t modtime Modification time 


The times in the utimbuf structure are measured in seconds since the 
Epoch §2.3. 
Upon successful completion, the utime() function shall mark for update the 
st_ctime field of the file. 
5.6.6.3 Returns. Upon successful completion, the function shall return a 
value of zero. Otherwise, a value of —1 shall be returned, errno is set to indicate 
the error, and the file times shall not be affected. 
5.6.6.4 Errors. If any of the following conditions occur, the utime() func- 
tion shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied by a component of the path prefix; 
or the times argument is NULL and the effective user ID of the 
process does not match the owner of the file and write access is 
denied. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The times argument is not NULL and the calling process’s effec- 
tive user ID has write access to the file but does not match the 
owner of the file and the calling process does not have the 
appropriate privileges. 

[EROFS] The named file resides on a read-only file system. 

5.6.6.5 References. <sys/stat.h> §5.6.1. 
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5.7 Configurable Pathname Variables. 


5.7.1 Get Configurable Pathname Variables. 
Functions: pathconf(), fpathconf() 


5.7.1.1 Synopsis. 
#include <unistd.h> 
long pathconf (path, name) 


char «path; 
int name; 


long fpathconf (fildes, name) 
int fildes, name; 


5.7.1.2 Description. The pathconf() and fpathconf() functions provide a 


method for the application to determine the current value of a configurable limit 
or option (variable ) that is associated with a file or directory. 

For pathconf(), the path argument points to the pathname of a file or direc- 
tory. For fpathconf(), the fildes argument is an open file descriptor. 

The name argument represents the variable to be queried relative to that file 
or directory. The implementation shall support all of the variables listed in 
Table 5-2 and may support others. The variables in Table 5-2 come from 
<limits.h> §2.9 or <unistd.h> §2.10 and the symbolic constants, defined in 
<unistd.h>, that are the corresponding values used for name. 


Table 5-2. Configurable Pathname Variables 


_________ Variable — name Value Notes 
{LINK_MAX} { PC_LINK_MAX} 1 
{MAX_CANON} {_ PC_MAX_CANON} Z 
{MAX_INPUT} { PC_MAX_INPUT} 2 
{NAME_MAX} { PC_NAME_MAX} 3,4 
{PATH_MAX} {_PC_PATH_MAX} 4,5 
{PIPE_BUF} (-PCoPIPE_BUF} 6 
{_POSIX_CHOWN_RESTRICTED} {_PC_CHOWN_RESTRICTED} 7 
{_POSIX_NO_TRUNC} { PC_NO_TRUNC} 3,4 
{ POSIX_VDISABLE} {_PC_VDISABLE} 2 


The following Notes apply to the entries in Table 5-2: 


i 


2. 
3. 


4. 
5 


If path or fildes refers to a directory, the value returned applies to the 
directory itself. 

The behavior is undefined if path or fildes does not refer to a terminal file. 
If path or fildes refers to a directory, the value returned applies to the 
filenames within the directory. 

The behavior is undefined if path or fildes does not refer to a directory. 

If path or fildes refers to a directory, the value returned is the maximum 
length of a relative pathname when the specified directory is the working 
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directory. 

6. If path refers to a FIFO, or filedes refers to a pipe or FIFO, the value 
returned applies to the referenced object itself. If path or fildes refers toa 
directory, the value returned applies to any FIFOs that exist or can be 
created within the directory. If path or fildes refer to any other type of file, 
the behavior is undefined. 

7. If path or fildes refer to a directory, the value returned applies to any files 
defined in this standard, other than directories, that exist or can be 
created within the directory. 
5.7.1.3 Returns. If name is an invalid value, the pathconf() and fpath- 

conf() functions shall return —-1. 

If the variable corresponding to name has no limit for the path or file descrip- 
tor, the pathconf() and fpathconf() functions shall return —1 without changing 
errno. 

If the implementation needs to use path to determine the value of name and 
the implementation does not support the association of name with the file speci- 
fied by path, or if the process did not have the appropriate privileges to query 
the file specified by path, or path does not exist, the pathconf() function shall 
return —1. 

If the implementation needs to use fildes to determine the value of name and 
the implementation does not support the association of name with the file speci- 
fied by fildes, or if fildes is an invalid file descriptor, the fpathconf() function 
shall return -1. 

Otherwise, the pathconf() and fpathconf() functions return the current vari- 
able value for the file or directory without changing errno. The value returned 
shall not be more restrictive than the corresponding value described to the 
application when it was compiled with the implementation’s <limits.h> §2.9 or 
<unistd.h> §2.10. 

5.7.1.4 Errors. If any of the following conditions occur, the pathconf() 
and fpathconf() functions shall return —1 and set errno to the corresponding 
value: 
[EINVAL] The value of name is invalid. 
For each of the following conditions, if the condition is detected, the path- 
conf() function shall return —1 and set errno to the corresponding value: 

[EACCES] Search permission is denied for a component of the path prefix. 

[EINVAL] The implementation does not support an association of the vari- 
able name with the specified file. 

[ENAMETOOLONG] 
The length of the path argument exceeds {PATH_MAX}, or a 
pathname component is longer than {NAME_MAX} while 
{ POSIX_NO_TRUNC} is in effect. 

[ENOENT] The named file does not exist or the path argument points to an 
empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

For each of the following conditions, if the condition is detected, the fpath- 
conf() function shall return —1 and set errno to the corresponding value: 
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[EBADF] The fildes argument is not a valid file descriptor. 
[EINVAL] The implementation does not support an association of the vari- 
able name with the specified file. 
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6. Input and Output Primitives 


The functions in this chapter deal with input and output from files and pipes. 
Functions are also specified which deal with the coordination and management 
of file descriptors and I/O activity. 


6.1 Pipes. 


6.1.1 Create an Inter-Process Channel. 
Function: pipe() 
6.1.1.1 Synopsis. 


int pipe (fildes) 
int fildes [2]; 


6.1.1.2 Description. The pipe() function shall create a pipe and place 
two file descriptors, one each into the arguments fildes[0] and fildes{1], that 
refer to the open file descriptions for the read and write ends of the pipe. Their 
integer values shall be the two lowest available at the time of the pipe() function 
call. The O_NONBLOCK flag shall be clear on both file descriptors. (The fentl() 
function can be used to set the O_NONBLOCK flag.) 

Data can be written to file descriptor fildes[1] and read from file descriptor 
fildes[0]. A read on file descriptor fildes[0] shall access the data written to file 
descriptor fildes[1] on a first-in-first-out basis. 

A process has the pipe open for reading if it has a file descriptor open that 
refers to the read end, fildes[0]. A process has the pipe open for writing if it has 
a file descriptor open that refers to the write end, fildes[1]. 

Upon successful completion, the pipe() function shall mark for update the 
st_atime, st_ctime, and st_mtime fields of the pipe. 

6.1.1.3 Returns. Upon successful completion, the function shall return a 
value of zero. Otherwise, a value of —1 shall be returned and errno shall be set 
to indicate the error. 

6.1.1.4 Errors. If any of the following conditions occur, the pipe() func- 
tion shall return —1 and set errno to the corresponding value: 

[EMFILE] More than {OPEN_MAX}-2 file descriptors are already in use by 

this process. 
[ENFILE] The number of simultaneously open files in the system would 
exceed a system-imposed limit. 
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6.1.1.5 References. fcnil() §6.5.2, open() §5.3.1, read() §6.4.1, write() 
§6.4.2. 


6.2 File Descriptor Manipulation. 


6.2.1 Duplicate an Open File Descriptor. 
Functions: dup(), dup2() 
6.2.1.1 Synopsis. 


int dup (fildes) 
int fildes; 


int dup2 (fildes, fildes2) 
int fildes, fildes2; 


6.2.1.2 Description. The dup() and dup2() functions provide an alter- 
nate interface to the service provided by the fentl() function using the F_DUPFD 
command. The call: 


Evd = dup  (titdes); 
shall be equivalent to: 
bid — tent (hides a) sDUE Dane): 
The call: 
fid = dup2 (fildes, fildes2); 
shall be equivalent to: 


close (fildes2); 
etlel SMieeoiell (semJkiches,, 18 ION), ioe s2)) 5 


except for the following: 
(1) If fildes2 is less than zero or greater than {OPEN_MAX}, the dup2() func- 
tion shall return —1 and errno shall be set to [EBADF]. 
(2) If fildes is a valid file descriptor and is equal to fildes2, the dup2() func- 
tion shall return fildes2 without closing it. 
(3) If fildes is not a valid file descriptor, dup2() shall fail and not close 
fildes2. 
6.2.1.3 Returns. Upon successful completion, the function shall return a 
file descriptor. Otherwise, a value of —1 shall be returned and errno shall be set 
to indicate the error. 
6.2.1.4 Errors. If any of the following conditions occur, the dup() and 
dup2() functions shall return —1 and set errno to the corresponding value: 
[EBADF] The argument fildes is not a valid open file descriptor or fildes2 
is out of range. 
[EMFILE] The number of file descriptors would exceed {OPEN_MAX}, or no 
file descriptors above fildes2 are available. 
6.2.1.5 References. close() §6.3.1, creat() §5.3.2, exec §3.1.2, fentlO 
§6.5.2, open() §5.3.1, pipe §6.1.1. 
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6.3 File Descriptor Deassignment. 


6.3.1 Close a File. 
Function: close() 
6.3.1.1 Synopsis. 


int close (fildes) 
int fildes; 


6.3.1.2 Description. The close() function shall deallocate (i.e., make 
available for return by subsequent open()’s, etc., executed by the process) the 
file descriptor indicated by fildes. All outstanding record locks owned by the 
process on the file associated with the file descriptor shall be removed (that is, 
unlocked). 

If the close() function is interrupted by a signal that is to be caught, it shall 
return —1 with errno set to [EINTR] and the state of fildes is unspecified. 

When all file descriptors associated with a pipe or FIFO special file have been 
closed, any data remaining in the pipe or FIFO shall be discarded. 

When all file descriptors associated with an open file description have been 
closed, the open file description shall be freed. 

If the link count of the file is zero, when all file descriptors associated with the 
file have been closed, the space occupied by the file shall be freed and the file 
shall no longer be accessible. 

6.3.1.3 Returns. Upon successful completion, a value of zero shall be 
returned. Otherwise, a value of —1 shall be returned and errno shall be set to 
indicate the error. 
6.3.1.4 Errors. If any of the following conditions occur, the close() func- 
tion shall return —1 and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[EINTR] The close function was interrupted by a signal. 
6.3.1.5 References. creat() §5.3.2, dup() §6.2.1, exec §3.1.2, fentl() §6.5.2, 
fork() §3.1.1, open() §5.3.1, pipe( §6.1.1, unlink() §5.5.1, Signal Effects on 
Other Functions §3.3.1.4. 


6.4 Input and Output. 


6.4.1 Read from a File. 
Function: read() 
6.4.1.1 Synopsis. 


int read (fildes, buf, nbyte) 
int fildes; 

char *buf; 

unsigned nbyte; 


6.4.1.2 Description. The read() function shall attempt to read nbyte 
bytes from the file associated with the open file descriptor, fildes, into the buffer 
pointed to by buf. 
If nbyte is zero, the read() function shall return zero and have no other 
results. 
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On a regular file or other file capable of seeking, read() shall start at a posi- 
tion in the file given by the file offset associated with fildes. Before successful 
return from read(), the file offset shall be incremented by the number of bytes 
actually read. 

On a file not capable of seeking, the read() shall start from the current posi- 
tion. The value of a file offset associated with such a file is undefined. 

Upon successful completion, the read() function shall return the number of 
bytes actually read and placed in the buffer. This number shall never be greater 
than nbyte. The value returned may be less than nbyte if the number of bytes 
left in the file is less than nbyte, if the read() request was interrupted by a sig- 
nal, or if the file is a pipe (or FIFO) or special file and has fewer than nbyte bytes 
immediately available for reading. For example, a read() from a file associated 
with a terminal may return one typed line of data. 

If a read() is interrupted by a signal before it reads any data, it shall return 
—1 with errno set to [EINTRI. 

If a read() is interrupted by a signal after it has successfully read some data, 
either it shall return —1 with errno set to [EINTR], or it shall return the number 
of bytes read. A read() from a pipe or FIFO shall never return with errno set to 
[EINTR] if it has transferred any data. 

No data transfer shall occur past the current end-of-file. If the starting posi- 
tion is at or after the end-of-file, zero shall be returned. If the file refers to a 
device special file, the result of subsequent read() requests is implementation- 
defined. 

If the value of nbyte is greater than {INT_MAX}, the result is implementation- 
defined. 

When attempting to read from an empty pipe (or FIFO): 

(1) If no process has the pipe open for writing, read() shall return zero to 
indicate end-of-file. 

(2) If some process has the pipe open for writing and O_NONBLOCK is set, 
read() shall return —1 and set errno to [EAGAIN]. 

(3) If some process has the pipe open for writing and O_NONBLOCK is clear, 
read() shall block until some data is written or the pipe is closed by all 
processes that had opened the pipe for writing. 

When attempting to read a file (other than a pipe or FIFO) that supports non- 
blocking reads and has no data currently available: 

(1) If O. NONBLOCK is set, read() shall return —1 and set errno to [EAGAIN]. 
(2) If O_NONBLOCK is clear, read() shall block until some data becomes 
available. 

(3) The use of the O_ NONBLOCK flag has no effect if there is some data avail- 
able. 

For any portion of a regular file, prior to the end-of-file, that has not been 
written, read() shall return bytes with value zero. 

Upon successful completion, the read() function shall mark for update the 
st_atime field of the file. 
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6.4.1.3 Returns. Upon successful completion, read() shall return an 
integer indicating the number of bytes actually read. Otherwise, read() shall 
return a value of —1 and set errno to indicate the error, and the content of the 
buffer pointed to by buf is indeterminate. 

6.4.1.4 Errors. If any of the following conditions occur, the read() func- 
tion shall return —1 and set errno to the corresponding value: 

[EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the pro- 
cess would be delayed in the read operation. 

[EBADF] The fildes argument is not a valid file descriptor open for read- 
ing. 

[EINTR] The read operation was interrupted by a signal, and either no 
data was transferred or the implementation does not report par- 
tial transfer for this file. 

[EIO] The implementation supports job control, the process is in a 
background process group and is attempting to read from its 
controlling terminal, and either the process is ignoring or block- 
ing the SIGTTIN signal or the process group of the process is 
orphaned. This error may also be_- generated for 
implementation-defined reasons. 

6.4.1.5 References. creat() §5.3.2, dup() §6.2.1, fentlQ §6.5.2, lseek() 
$6.5.3, open() §5.3.1, pipeQ §6.1.1, Signal Effects on Other Functions 
§3.3.1.4, terminal Interface Characteristics §7.1.1. 


6.4.2 Write to a File. 
Function: write() 
6.4.2.1 Synopsis. 


int write (fildes, buf, nbyte) 
int fildes; 

char *buf; 

unsigned nbyte; 


6.4.2.2 Description. The write() function shall attempt to write nbyte 
bytes from the buffer pointed to by buf to the file associated with the open file 
descriptor, fildes. 

If nbyte is zero, the write() function shall return zero and have no other 
results if the file is a regular file; otherwise, the results are implementation- 
defined. : 

On a regular file or other file capable of seeking, the actual writing of data 
shall proceed from the position in the file indicated by the file offset associated 
with fildes. Before successful return from write(), the file offset shall be incre- 
mented by the number of bytes actually written. On a regular file, if this incre- 
mented file offset is greater than the length of the file, the length of the file 
shall be set to this file offset. 

On a file not capable of seeking, the write() shall start from the current posi- 
tion. The value of a file offset associated with such a file is undefined. 

If the O_LAPPEND flag of the file status flags is set, the file offset shall be set to 
the end of the file prior to each write. 
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If a write() requests that more bytes be written than there is room for (for 
example, the physical end of a medium), only as many bytes as there is room for 
shall be written. For example, suppose there is space for 20 bytes more in a file 
before reaching a limit. A write of 512 bytes would return 20. The next write of 
a non-zero number of bytes would give a failure return (except as noted below). 

Upon successful completion, the write() function shall return the number of 
bytes actually written to the file associated with fildes. This number shall 
never be greater than nbyte. 

If a write() is interrupted by a signal before it writes any data, it shall return 
—1 with errno set to [EINTR]. 

If write() is interrupted by a signal after it successfully writes some data, 
either it shall return —1 with errno set to [EINTR], or it shall return the number 
of bytes written. A write() to a pipe or FIFO shall never return with errno set to 
[EINTR] if it has transferred any data and nbyte is less than or equal to 
{PIPE_BUF}. 

If the value of nbyte is greater than {INT_MAX}, the result is implementation- 
defined. 

Write requests to a pipe (or FIFO) shall be handled the same as a regular file 
with the following exceptions: 

(1) There is no file offset associated with a pipe, hence each write request 
shall append to the end of the pipe. 

(2) Write requests of {PIPE_BUF} bytes or less shall not be interleaved with 
data from other processes doing writes on the same pipe. Writes of greater 
than {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, 
with writes by other processes, whether or not the O_NONBLOCK flag of the 
file status flags is set. 

(3) If the O_NONBLOCK flag is clear, a write request may cause the process 
to block, but on normal completion it shall return nbyte. 

(4) If the O_NONBLOCK flag is set, write() requests shall be handled dif- 
ferently, in the following ways: the write() function shall not block the pro- 
cess; write requests for {PIPE_BUF} or fewer bytes shall either succeed com- 
pletely and return nbyte, or return -1 and set errno to [EAGAIN]; a write() 
request for greater than {PIPE_BUF} bytes shall either transfer what it can 
and return the number of bytes written, or transfer no data and return —1 
with errno set to [EAGAIN]. Also, if a write() request is greater than 
{PIPE_BUF} bytes and all data previously written to the pipe has been read, 
write() shall transfer at least {PIPE_BUF} bytes. 

When attempting to write to a file descriptor (other than a pipe or FIFO) that 
supports nonblocking writes and cannot accept the data immediately: 

(1) If the O_NONBLOCK flag is clear, write() shall block until the data can be 
accepted. 

(2) If the O_.NONBLOCK flag is set, write() shall not block the process. If 
some data can be written without blocking the process, write() shall write 
what it can and return the number of bytes written. Otherwise, it shall 
return —1 and errno shall be set to [EAGAIN]. 

Upon successful completion, the write() function shall mark for update the 
st_ctime and st_mtime fields of the file. 
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6.4.2.3 Returns. Upon successful completion, write() shall return an 
integer indicating the number of bytes actually written. Otherwise, it shall 
return a value of —1 and set errno to indicate the error. 

6.4.2.4 Errors. If any of the following conditions occur, the write() func- 
tion shall return —1 and set errno to the corresponding value: 


[EAGAIN] 
[EBADF] 
[EFBIG] 


[EINTR] 


[EIO] 


[ENOSPC] 


[EPIPE] 


The O_NONBLOCK flag is set for the file descriptor and the pro- 
cess would be delayed in the write operation. 

The fildes argument is not a valid file descriptor open for writ- 
ing. 

An attempt was made to write a file that exceeds an 
implementation-defined maximum file size. 

The write operation was interrupted by a signal, and either no 
data was transferred or the implementation does not report par- 
tial transfers for this file. 

The implementation supports job control, the process is in a 
background process group and is attempting to write to its con- 
trolling terminal, TOSTOP is set, the process is neither ignoring 
nor blocking SIGTTOU signals, and the process group of the pro- 
cess is orphaned. This error may also be generated for 
implementation-defined reasons. 

There is no free space remaining on the device containing the 
file. 

An attempt is made to write to a pipe (or FIFO) that is not open 
for reading by any process. A SIGPIPE signal shall also be sent 
to the process. 


6.4.2.5 References. creat() §5.3.2, dup() §6.2.1, fentl() §6.5.2, lseek() 
§6.5.3, open() §5.3.1, pipe() §6.1.1, Signal Effects on Other Functions 


§3.3.1.4. 


6.5 Control Operations on Files. 


Table 6-1. cmd Values for fentl(. 


Constant Description 
F_DUPFD Duplicate file descriptor. 
F_GETFD Get file descriptor flags. 
F_GETLK Get record locking information. 
F_SETFD Set file descriptor flags. 
F_GETFL Get file status flags. 
F_SETFL Set file status flags. 
F_SETLK Set record locking information. 
F_SETLKW Set record locking information; wait if blocked. 
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Table 6-2. File Descriptor Flags Used For fentl(). 


Constant Description — 
FD_CLOEXEC Close the file descriptor upon execution of an exec- 


family function. 


Table 6-3. /_type Values For Record Locking With fentl(). 


Constant Description 
F_RDLCK Shared or read lock. 
F_UNLCK Unlock. 
F_WRLCK Exclusive or write lock. 


Table 6-4. oflag Values For open(). 


Constant Description 
O_CREAT Create file if it doesn’t exist. 
O_EXCL Exclusive use flag. 

O_NOCTTY Don’t assign a controlling terminal. 
O_TRUNC Truncate flag. 


Table 6-5. File Status Flags Used For open() and fentl(). 
Constant Description 


O_APPEND Set append mode. 
O_NONBLOCK No delay. 


Table 6-6. File Access Modes Used For open() and fenitl(). 


Constant Description 
O_RDONLY Open for reading only. 
O_RDWR Open for reading and writing. 
O_WRONLY Open for writing only. 


6.5.1 Data Definitions for File Control Operations. The header 
<fcntl.h> defines the following requests and arguments for the fentl() §6.5.2 and 
open() §5.3.1 functions. The values within each of the Tables 6-1 through 6-7 
shall be unique numbers. In addition, the values of the entries for oflag values, 
file status flags, and file access modes shall be unique. 
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Table 6-7. Mask For Use With File Access Modes. 


Constant Description 
O_ACCMODE Mask for file access modes. 


6.5.2 File Control. 


Function: fentl( 


) 


6.5.2.1 Synopsis. 


#include < 
#include < 
#include < 


sys/types.h> 
unistd.h> 
fentl.h> 


int fentl (fildes, cmd,...) 
int fildes, cmd; 


6.5.2.2 Description. The function fent/() provides for control over open 
files. The argument fildes is a file descriptor. 


The available 


values for cmd are defined in the er <fentl.h> §6.5.1, 


which shall include: 


F_DUPFD 


F_GETFD 


F_SETFD 


F_GETFL 


F_SEPFL 


Return a new file descriptor which is the lowest numbered 
available (i.e., not already open) file descriptor greater than or 
equal to the third argument, arg, taken as an integer of type 
int. The new file descriptor refers to the same open file descrip- 
tion as the original file descriptor, and shares any locks. 

The FD_CLOEXEC flag associated with the new file descriptor 
is cleared to keep the file open across calls to the exec family of 
functions. 

Get the file descriptor flags defined in Table 6-2 that are associ- 
ated with the file descriptor fildes. File descriptor flags are 
associated with a single file descriptor and do not affect other 
file descriptors that refer to the same file. 

Set the file descriptor flags defined in Table 6-2 that are associ- 
ated with fildes, to the third argument, arg, taken as type int. 
If the FD_CLOEXEC flag is zero, the file shall remain open 
across exec functions; otherwise, the file shall be closed upon 
successful execution of an exec function. 

Get the file status flags, defined in Table 6-5 and file access 
modes for the open file description associated with fildes. The 
file access modes defined in Table 6-6 can be extracted from the 
return value using the mask O_ACCMODE, which is defined in 
<fentl.h> §6.5.1. File status flags and file access modes are 
associated with the open file description and do not affect other 
file descriptors that refer to the same file with different open 
file descriptions. 

Set the file status flags, defined in Table 6-5 for the open file 
description associated with fildes from the corresponding bits in 
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the third argument, arg, taken as type int. The file access 
mode shall not be changed by this function call. If any other 
bits are set in arg, the result is implementation-defined. 
The following commands are available for advisory record locking. Advisory 
record locking shall be supported for regular files, and may be supported for 
other files. 

F_GETLK _ Get the first lock which blocks the lock description pointed to by 
the third argument, arg, taken as a pointer to type struct flock 
(see below). The information retrieved overwrites the informa- 
tion passed to fcnétl() in the flock structure. If no lock is found 
that would prevent this lock from being created, the structure 
shall be left unchanged by this function call except for the lock 
type which shall be set to F_LUNLCK. 

F_SETLK _ Set or clear a file segment lock according to the lock description 
pointed to by the third argument, arg, taken as a pointer to 
type struct flock (see below). F_SETLK is used to establish 
shared (or read) locks (F_RDLCK) or exclusive (or write) locks, 
(F_WRLCK), as well as to remove either type of lock (F_UNLCK). 
F_RDLCK, F_WRLCK, and F_UNLCK are defined by the 
<fentl.h> §6.5.1 header. If a shared or exclusive lock cannot be 
set, fentl() shall return immediately. 

F_SETLKW This command is the same as F_SETLK except that if a shared 
or exclusive lock is blocked by other locks, the process shall wait 
until the request can be satisfied. If a signal that is to be 
caught is received while fcntl() is waiting for a region, the 
fentlQ shall be interrupted. Upon return from the process’s sig- 
nal handler, fentl() shall return —1 with errno set to [EINTR], 
and the lock operation shall not be done. 

The flock structure, defined by the <fentl.h> §6.5.1 header, describes an 
advisory lock. It includes the members shown in Table 6-8. 


Table 6-8. flock Structure 


Member Member 


Tae Neaae Description 
short l_type F_RDLCK, F_WRLCK, or F_UNLCK. 
short l_whence Flag for starting offset. 
off_t l_ start Relative offset in bytes. 
off_t l_len Size; if 0 then until EOF. 
pid_t l_pid Process ID of the process holding the lock, 


returned with F_GETLK. 


When a shared lock has been set on a segment of a file, other processes shall 
be able to set shared locks on that segment or a portion of it. A shared lock 
prevents any other process from setting an exclusive lock on any portion of the 
protected area. A request for a shared lock shall fail if the file descriptor was 
not opened with read access. 
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An exclusive lock shall prevent any other process from setting a shared lock 
or an exclusive lock on any portion of the protected area. A request for an 
exclusive lock shall fail if the file descriptor was not opened with write access. 

The value of /_whence is SEEK_SET, SEEK_CUR, or SEEK_END to indicate that 
the relative offset, /_start bytes, will be measured from the start of the file, 
current position, or end of the file, respectively. The value of /_len is the 
number of consecutive bytes to be locked. If /_len is negative, the result is 
implementation-defined. The /_pid field is only used with F_GETLK to return 
the process ID of the process holding a blocking lock. After a successful 
F_GETLK request, the value of /_whence shall be SEEK_SET. 

Locks may start and extend beyond the current end of a file, but shall not 
start or extend before the beginning of the file. A lock shall be set to extend to 
the largest possible value of the file offset for that file if /_len is set to zero. If 
the flock struct has l_whence and /_start that point to the beginning of the file, 
and /_len of zero, the entire file shall be locked. 

The calling process shall have only one type of lock set for each byte in the 
file. Before successful return from a F_LSETLK or F_SETLKW request, the previ- 
ous lock type for each byte in the specified region shall be replaced by the new 
lock type. All locks associated with a file for a given process shall be removed 
when a file descriptor for that file is closed by that process or the process hold- 
ing that file descriptor terminates. Locks are not inherited by a child process 
created using the fork() function. 

A potential for deadlock occurs if a process controlling a locked region is put 
to sleep by attempting to lock another process’s locked region. If the system 
detects that sleeping until a locked region is unlocked would cause a deadlock, 
the fentl() function shall fail with an [EDEADLK] error. 

6.5.2.3 Returns. Upon successful completion, the value returned shall 
depend oncmd. The various return values are shown in Table 6-9. 


Table 6-9. fent/() Return Values 


Request Return Value 

F_DUPFD A new file descriptor. 

F_GETFD Value of the flags defined in Table 6-2, but the 
return value shall not be negative. 

F_SETFD Value other than -1. 

F_GETFL Value of file status flags and access modes, but the 
return value shall not be negative. 

F_SETFL Value other than —1. 

F_GETLK Value other than -1. 

F_SETLK Value other than -1. 

F_SETLKW Value other than -1. 


Otherwise, a value of —1 shall be returned and errno shall be set to indicate 
the error. 
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6.5.2.4 Errors. If any of the following conditions occur, the fentl() func- 
tion shall return —1 and set errno to the corresponding value: 
[EACCES] or [EAGAIN] 


[EBADF] 


[EINTR] 


[EINVAL] 


[EMFILE] 


[ENOLCK] 


The argument cmd is F_SETLK, the type of lock (/_type) is a 
shared lock (F_RDLCK) or exclusive lock (F_WRLCK), and the 
segment of a file to be locked is already exclusive-locked by 
another process, or the type is an exclusive lock and some por- 
tion of the segment of a file to be locked is already shared- 
locked or exclusive-locked by another process. 

The fildes argument is not a valid file descriptor. 

The argument cmd is F_SETLK or F_SETLKW,, the type of lock 
(l_type) is a shared lock (F_RDLCK), and fildes is not a valid file 
descriptor open for reading. 

The argument cmd is F_SETLK or F_SETLKW, the type of lock 
(1_type) is an exclusive lock (F_WRLCK), and fildes is not a valid 
file descriptor open for writing. 

The argument cmd is F_SETLKW and the function was inter- 
rupted by a signal. 

The argument cmd is F_DUPFD and the third argument is nega- 
tive or greater than or equal to {OPEN_MAX}. 

The argument cmd is F_GETLK, F_SETLK, or F_SETLKW and 
the data arg points to is not valid, or fildes refers to a file that 
does not support locking. 

The argument cmd is F_DUPFD and {OPEN_MAX} file descrip- 
tors are currently in use by this process, or no file descriptors 
greater than or equal to arg are available. 

The argument cmd is F_SETLK or F_SETLKW and satisfying the 
lock or unlock request would result in the number of locked 
regions in the system exceeding a system-imposed limit. 


For each of the following conditions, if the condition is detected, the fcntl() 
function shall return —1 and set errno to the corresponding value: 
[EDEADLK] The argument cmd is F_SETLKW and a deadlock condition was 


detected. 


6.5.2.5 References. close() §6.3.1, exec §3.1.2, open() §5.3.1, <fentl.h> 
§6.5.1, Signal Effects on Other Functions §3.3.1.4. 


6.5.3. Reposition Read/Write File Offset. 
Function: /seek() 
6.5.3.1 Synopsis. 


#include <sys/types.h> 
#include <unistd.h> 


off_t lseek (fildes, offset, whence) 
int fildes, whence; 
off_t offset; 
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6.5.3.2 Description. The fi/Jdes argument is an open file descriptor. The 

lseek() function shall set the file offset for the open file description associated 
with fildes as follows: 

(1) If whence is SEEK_SET, the offset is set to offset bytes. 

(2) If whence is SEEK_CUR, the offset is set to its current value plus offset 

bytes. 

(3) If whence is SEEK_END, the offset is set to the size of the file plus offset 

bytes. 

The symbolic constants SEEK_SET, SEEK_CUR, SEEK_END are defined in the 
header <unistd.h> $2.10. 

Some devices are incapable of seeking. The value of the file offset associated 
with such a device is undefined. The behavior of the /seek() function on such 
devices is implementation-defined. 

The /seek() function shall allow the file offset to be set beyond the end of exist- 
ing data in the file. If data is later written at this point, subsequent reads of 
data in the gap shall return bytes with the value zero until data is actually writ- 
ten into the gap. 

The /seek() function shall not, by itself, extend the size of a file. 

6.5.3.3 Returns. Upon successful completion, the function shall return 
the resulting offset location as measured in bytes from the beginning of the file. 
Otherwise, it shall return a value of ((off_t) -1), shall set errno to indicate the 
error, and the file offset shall remain unchanged by this function call. 
6.5.3.4 Errors. If any of the following conditions occur, the /seek() func- 
tion shall return —1 and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[EINVAL] The whence argument is not a proper value, or the resulting file 
offset would be invalid. 
[ESPIPE] The fildes argument is associated with a pipe or FIFO. 
6.5.3.5 References. creat() §5.3.2, dup() $6.2.1, fentlO $6.5.2, open() 
$5.3.1, read() §6.4.1, sigaction() $3.3.4, write() $6.4.2, <unistd.h> §2.10. 
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7. Device- and Class-Specific Functions 


7.1 General Terminal Interface. This section describes a general terminal 
interface that shall be provided to control asynchronous communications ports. 
It is implementation-defined whether this interface supports network connec- 
tions or synchronous ports or both. Certain functions in this chapter apply only 
to the controlling terminal of a process. Where this is the case it will be so 
noted. 


7.1.1 Interface Characteristics. 
7.1.1.1 Opening a Terminal Device File. When a terminal file is 
opened, it normally causes the process to wait until a connection is established. 
In practice, application programs seldom open these files; they are opened by 
special programs and become an application’s standard input, output, and error 
files. 

As described in open() §5.3.1, opening a terminal device file with the 
O_NONBLOCK flag clear shall cause the process to block until the terminal dev- 
ice is ready and available. The CLOCAL flag can also affect open(). See Control 
Modes $7.1.2.4. 

7.1.1.2 Process Groups. A terminal may have a foreground process 
group associated with it. This foreground process group plays a special role in 
handling signal-generating input characters, as discussed below in Special 
Characters §7.1.1.9. 

If the implementation supports job control Gf {_POSIX_JOB_CONTROL]} is 
defined; see Symbolic Constants §2.10), command interpreter processes* sup- 
porting job control can allocate the terminal to different jobs, or process groups, 
by placing related processes in a single process group and associating this pro- 
cess group with the terminal. A terminal’s foreground process group may be set 
or examined by a process, assuming the permission requirements in this section 
are met; see tcgetpgrp() §7.2.3 and tcsetpgrp() §7.2.4. The terminal interface 
aids in this allocation by restricting access to the terminal by processes that are 
not in the foreground process group; see Terminal Access Control §7.1.1.4. 


* The P1003.2 Working Group is working on a definition and description of command interpreters. 
See Shell and Utilities §A.2.3. 
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7.1.1.3 The Controlling Terminal. A terminal may belong to a process 
as its controlling terminal. Each process of a session that has a controlling ter- 
minal has the same controlling terminal. A terminal may be the controlling ter- 
minal for at most one session. The controlling terminal for a session is allocated 
by the session leader in an implementation-defined manner. If a session leader 
has no controlling terminal, and opens a terminal device file that is not already 
associated with a session without using the O_NOCTTY option (see open() 
§5.3.1), it is implementation-defined whether the terminal becomes the control- 
ling terminal of the session leader. If a process which is not a session leader 
opens a terminal file, or the O_NOCTTY option is used on open(), that terminal 
shall not become the controlling terminal of the calling process. When a control- 
ling terminal becomes associated with a session, its foreground process group 
shall be set to the process group of the session leader. 

The controlling terminal is inherited by a child process during a fork() func- 
tion. A process relinquishes its controlling terminal when it creates a new ses- 
sion with the setsid() function, or when all file descriptors associated with the 
controlling terminal have been closed. 

When a controlling process terminates, the controlling terminal is disassoci- 
ated from the current session, allowing it to be acquired by a new session leader. 
Subsequent access to the terminal by other processes in the earlier session may 
be denied, with attempts to access the terminal treated as if modem disconnect 
had been sensed. 

7.1.1.4 Terminal Access Control. If a process is in the foreground pro- 
cess group of its controlling terminal, read operations shall be allowed as 
described in Input Processing and Reading Data §7.1.1.5. For those imple- 
mentations that support job control, any attempts by a process in a background 
process group to read from its controlling terminal shall cause its process group 
to be sent a SIGTTIN signal unless one of the following special cases apply: If 
the reading process is ignoring or blocking the SIGTTIN signal, or if the process 
group of the reading process is orphaned, the read() returns —1 with errno set to 
[EIO] and no signal is sent. The default action of the SIGTTIN signal is to stop 
the process to which it is sent. See Signal Names §3.3.1.1. 

If a process is in the foreground process group of its controlling terminal, 
write operations shall be allowed as described in Writing Data and Output 
Processing §7.1.1.8. Attempts by a process in a background process group to 
write to its controlling terminal shall cause the process group to be sent a 
SIGTTOU signal unless one of the following special cases apply: If TOSTOP is not 
set, or if TOSTOP is set and the process is ignoring or blocking the SIGTTOU sig- 
nal, the process is allowed to write to the terminal and the SIGTTOU signal is 
not sent. If TOSTOP is set, and the process group of the writing process is 
orphaned, and the writing process is not ignoring or blocking SIGTTOU, the 
write() returns —1 with errno set to [EIO] and no signal is sent. 

Certain calls that set terminal parameters are treated in the same fashion as 
write, except that TOSTOP is ignored; that is, the effect is identical to that of ter- 
minal writes when TOSTOP is set. See Control Functions $7.2. 
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7.1.1.5 Input Processing and Reading Data. A terminal device associ- 
ated with a terminal device file may operate in full-duplex mode, so that data 
may arrive even while output is occurring. Each terminal device file has associ- 
ated with it an input queue, into which incoming data is stored by the system 
before being read by a process. The system may impose a limit, {MAX_INPUT}, 
on the number of bytes that may be stored in the input queue. The behavior of 
the system when this limit is exceeded is implementation-defined. 

Two general kinds of input processing are available, determined by whether 
the terminal device file is in canonical mode or non-canonical mode. These 
modes are described in Canonical Mode Input Processing §7.1.1.6 and 
Non-Canonical Mode Input Processing §7.1.1.7. Additionally, input charac- 
ters are processed according to the c_iflag (see Input Modes §7.1.2.2) and 
c_lflag (see Local Modes §7.1.2.5) fields. Such processing can include echoing, 
which in general means transmitting input characters immediately back to the 
terminal when they are received from the terminal. This is useful for terminals 
that can operate in full-duplex mode. 

The manner in which data is provided to a process reading from a terminal 
device file is dependent on whether the terminal device file is in canonical or 
non-canonical mode. 

Another dependency is whether the O_LNONBLOCK flag is set by open() or 
fentl(). If the O_NONBLOCK flag is clear, then the read request shall be blocked 
until data is available or a signal has been received. If the O_.NONBLOCK flag is 
set, then the read request shall be completed, without blocking, in one of three 
ways: 

(1) If there is enough data available to satisfy the entire request, the read() 
shall complete successfully and return the number of bytes read. 

(2) If there is not enough data available to satisfy the entire request, the 
read() shall complete successfully, having read as much data as possible, and 
return the number of bytes it was able to read. 

(3) If there is no data available, the read() shall return —1, with errno set to 
[EAGAIN]. 

When data is available depends on whether the input processing mode is 
canonical or non-canonical. The following sections, Canonical Mode Input 
Processing §7.1.1.6 and Non-Canonical Mode Input Processing §7.1.1.7, 
describe each of these input processing modes. 

7.1.1.6 Canonical Mode Input Processing. In canonical mode input 
processing, terminal input is processed in units of lines. A line is delimited by a 
newline (’\n’). character, an end-of-file (EOF) character, or an end-of-line (EOL) 
character. See Special Characters §7.1.1.9 for more information on EOF and 
EOL. This means that a read request shall not return until an entire line has 
been typed, or a signal has been received. Also, no matter how many bytes are 
requested in the read call, at most one line shall be returned. It is not, however, 
necessary to read a whole line at once; any number of bytes, even one, may be 
requested in a read without losing information. 

If {MAX CANON} is defined for this terminal device, it is a limit on the number 
of bytes in a line. The behavior of the system when this limit is exceeded is 
implementation-defined. If {MAX CANON} is not defined, there is no such limit; 
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see Pathname Variable Values §2.9.5. 

Erase and kill processing occur when either of two special characters, the 
ERASE and KILL characters (see Special Characters §7.1.1.9), is received. 
This processing affects data in the input queue that has not yet been delimited 
by a newline (NL), EOF, or EOL character. This un-delimited data makes up the 
current line. The ERASE character deletes the last character in the current line, 
if there is any. The KILL character deletes all data in the current line, if there 
is any. The ERASE and KILL characters have no effect if there is no data in the 
current line. The ERASE and KILL characters themselves are not placed in the 
input queue. 

7.1.1.7 Non-Canonical Mode Input Processing. In non-canonical 
mode input processing, input bytes are not assembled into lines, and erase and 
kill processing does not occur. The values of the MIN and TIME members of the 
c_cc array are used to determine how to process the bytes received. 

MIN represents the minimum number of bytes that should be received when 
the read() function successfully returns. TIME is a timer of 0.1 second granular- 
ity that is used to time out bursty and short term data transmissions. If MIN is 
greater than {MAX_INPUT}, the response to the request is implementation- 
defined. The four possible values for MIN and TIME and their interactions are 
described below. 

7.1.1.7.1 Case A: MIN > 0, TIME > 0. In this case TIME serves as an 
inter-byte timer and is activated after the first byte is received. Since it is an 
inter-byte timer, it is reset after a byte is received. The interaction between 
MIN and TIME is as follows: as soon as one byte is received, the inter-byte timer 
is started. If MIN bytes are received before the inter-byte timer expires 
(remember that the timer is reset upon receipt of each byte), the read is satis- 
fied. If the timer expires before MIN bytes are received, the characters received 
to that point are returned to the user. Note that if TIME expires at least one 
byte shall be returned because the timer would not have been enabled unless a 
byte was received. In this case (MIN > 0, TIME > 0) the read shall block until the 
MIN and TIME mechanisms are activated by the receipt of the first byte, or a 
signal is received. 

7.1.1.7.2 Case B: MIN > 0, TIME = 0. In this case, since the value of 
TIME is zero, the timer plays no role and only MIN is significant. A pending 
read is not satisfied until MIN bytes are received (i.e., the pending read shall 
block until MIN bytes are received), or a signal is received. A program that uses 
this case to read record-based terminal I/O may block indefinitely in the read 
operation. 

7.1.1.7.8 Case C: MIN = 0, TIME > 0. In this case, since MIN = 0, TIME 
no longer represents an inter-byte timer. It now serves as a read timer that is 
activated as soon as the read() function is processed. A read is satisfied as soon 
as a single byte is received or the read timer expires. Note that in this case if 
the timer expires, no bytes shall be returned. If the timer does not expire, the 
only way the read can be satisfied is if a byte is received. In this case the read 
shall not block indefinitely waiting for a byte; if no byte is received within 
TIME*0.1 seconds after the read is initiated, the read() shall return a value of 
zero, having read no data. 
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7.1.1.7.4 Case D: MIN = 0, TIME = 0. The minimum of either the 

number of bytes requested or the number of bytes currently available shall be 
returned without waiting for more bytes to be input. If no characters are avail- 
able, read() shall return a value of zero, having read no data. 

7.1.1.8 Writing Data and Output Processing. When a process writes 
one or more bytes to a terminal device file, they are processed according to the 
c_oflag field (see Output Modes §7.1.2.3). The implementation may provide a 
buffering mechanism; as such, when a call to write() completes, all of the bytes 
written have been scheduled for transmission to the device, but the transmis- 
sion will not necessarily have completed. See also write() §6.4.2 for the effects of 
O_NONBLOCK on write(). 

7.1.1.9 Special Characters. Certain characters have special functions 
on input or output or both. These functions are summarized as follows: 

INTR Special character on input and is recognized if the ISIG flag (see 
Local Modes §7.1.2.5) is enabled. Generates a SIGINT signal 
which is sent to all processes in the foreground process group 
for which the terminal is the controlling terminal. If ISIG is set, 
the INTR character is discarded when processed. 

QUIT Special character on input and is recognized if the ISIG flag is 
enabled. Generates a SIGQUIT signal which is sent to all 
processes in the foreground process group for which the termi- 
nal is the controlling terminal. If ISIG is set, the QUIT charac- 
ter is discarded when processed. 

ERASE Special character on input and is recognized if the ICANON flag 
is set. Erases the last character in the current line; see Canon- 
ical Mode Input Processing §7.1.1.6. It shall not erase 
beyond the start of a line, as delimited by an NL, EOF, or EOL 
character. If ICANON is set, the ERASE character is discarded 
when processed. 

KILL Special character on input and is recognized if the ICANON flag 
is set. Deletes the entire line, as delimited by a NL, EOF, or 
EOL character. If ICANON is set, the KILL character is dis- 
carded when processed. 

EOF Special character on input and is recognized if the ICANON flag 
is set. When received, all the bytes waiting to be read are 
immediately passed to the process, without waiting for a new- 
line, and the EOF is discarded. Thus, if there are no bytes wait- 
ing (that is, the EOF occurred at the beginning of a line), a byte 
count of zero shall be returned from the read(), representing an 
end-of-file indication. If ICANON is set, the EOF character is 
discarded when processed. 


NL Special character on input and is recognized if the ICANON flag 
is set. It is the line delimiter (’\n’). 

EOL Special character on input and is recognized if the ICANON flag 
is set. Is an additional line delimiter, like NL. 

SUSP If job control is supported (see Special Control Characters 


§7.1.2.6), the SUSP special character is recognized on input. If 
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the ISIG flag is enabled, receipt of the SUSP character causes a 
SIGTSTP signal to be sent to all processes in the foreground pro- 
cess group for which the terminal is the controlling terminal, 
and the SUSP character is discarded when processed. 

STOP Special character on both input and output and is recognized if 
the IXON (output control) or IXOFF (input control) flag is set. 
Can be used to temporarily suspend output. It is useful with 
CRT terminals to prevent output from disappearing before it 
can be read. If IXON is set, the STOP character is discarded 
when processed. 

START Special character on both input and output and is recognized if 
the IXON (output control) or IXOFF (input control) flag is set. 
Can be used to resume output that has been suspended by a 
STOP character. If IXON is set, the START character is dis- 
carded when processed. 

CR Special character on input and is recognized if the ICANON flag 
is set; it is the ’\r’. When ICANON and ICRNL are set and 
IGNCR is not set, this character is translated into a NL, and has 
the same effect as a NL character. 

The NL and CR characters cannot be changed. It is implementation-defined 
whether the START and STOP characters can be changed. The values for INTR, 
QUIT, ERASE, KILL, EOF, EOL, and SUSP (job control only), shall be changeable 
to suit individual tastes. 

If {_POSIX_VDISABLE} is in effect for the terminal file, special character func- 
tions associated with changeable special control characters can be disabled indi- 
vidually; see Special Control Characters §7.1.2.6. 

If two or more special characters have the same value, the function performed 
when that character is received is undefined. 

A special character is recognized not only by its value, but also by its context; 
for example, an implementation may define multibyte sequences that have a 
meaning different from the meaning of the bytes when considered individually. 
Implementations may also define additional single-byte functions. These 
implementation-defined multibyte or single byte functions are recognized only if 
the IEXTEN flag is set; otherwise, data is interpreted as normal characters or as 
the special characters defined in this section. 

7.1.1.10 Modem Disconnect. If a modem disconnect is detected by the 
terminal interface for a controlling terminal, and if CLOCAL is not set in the 
c_cflag field for the terminal (see Control Modes §7.1.2.4), the SIGHUP signal 
is sent to the controlling process associated with the terminal. Unless other 
arrangements have been made, this causes the controlling process to terminate; 
see _exit() §3.2.2. Any subsequent read from the terminal device returns with 
an end-of-file indication until the device is closed. Thus, processes that read a 
terminal file and test for end-of-file can terminate appropriately after a discon- 
nect. Any subsequent write() to the terminal device returns —1, with errno set 
to [EIO], until the device is closed. 


128 Device- and Class-Specific Functions 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


7.1.1.11 Closing a Terminal Device File. The last process to close a ter- 
minal device file shall cause any output to be sent to the device and any input to 
be discarded. Then, if HUPCL is set in the control modes, and the communica- 
tions port supports a disconnect function, the terminal device shall perform a 
disconnect. 


7.1.2 Settable Parameters. 
7.1.2.1 termios Structure. Routines that need to control certain terminal 
VO characteristics shall do so by using the termios structure as defined in the 
header <termios.h>. The members of this structure include (but are not lim- 
ited to) those shown in Table 7-1. 


Table 7-1. termios Structure 


Member Array Member 


Type Size Name wei ciel 
tcflag_t c_iflag Input modes 
tcflag_t c_oflag Output modes 
tcflag_t c_cflag Control modes 
tcflag_t c_lflag Local modes 
CCut NOCS  c_ce Control characters 


The types tcflag_t and cc_t shall be defined in the header <termios.h>. They 
shall be unsigned integral types. 
The total size of the termios structure is implementation-defined. 
7.1.2.2 Input Modes. Values of the c_iflag field, shown in Table 7-2, 
describe the basic terminal input control, and are composed of the bitwise 
inclusive OR of the masks shown, which shall be bitwise distinct. The mask 
name symbols in this table are defined in <termios.h>. 


Table 7-2. termios c_iflag Field 


Mask 
Name 


BRKINT Signal interrupt on break. 
ICRNL Map CR to NL on input. 

IGNBRK Ignore break condition. 

IGNCR Ignore CR. 

IGNPAR Ignore characters with parity errors. 
INLCR Map NL to CR on input. 

INPCK Enable input parity check. 
ISTRIP Strip character. 

IXOFF Enable start/stop input control. 
IXON Enable start/stop output control. 
PARMRK Mark parity errors. 


Description 
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In the context of asynchronous serial data transmission, a break condition is 
defined as a sequence of zero-valued bits that continues for more than the time 
to send one byte. The entire sequence of zero-valued bits is interpreted as a sin- 
gle break condition, even if it continues for a time equivalent to more than one 
byte. In contexts other than asynchronous serial data transmission the defini- 
tion of a break condition is implementation-defined. 

If IGNBRK is set, a break condition detected on input is ignored, that is, not 
put on the input queue and therefore not read by any process. If IGNBRK is not 
set and BRKINT is set, the break condition shall flush the input and output 
queues and if the terminal is the controlling terminal of a foreground process 
group, the break condition shall generate a single SIGINT signal to that fore- 
ground process group. If neither IGNBRK nor BRKINT is set, a break condition 
is read as a single ’\0’, or if PARMRK is set, as ’\377’, ’\0’, ’\0’. 

If IGNPAR is set, a byte with a framing or parity error (other than break) is 
ignored. 

If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity error 
(other than break) is given to the application as the three-character sequence 
"\377', ’\0’, X, where ’\377’, ’\0’ is a two-character flag preceding each 
sequence and X is the data of the character received in error. To avoid ambi- 
guity in this case, if ISTRIP is not set, a valid character of ’\377’ is given to the 
application as ’\377’, ‘\377’. If neither PARMRK nor IGNPAR is set, a framing 
or parity error (other than break) is given to the application as a single charac- 
ar 0) 

If INPCK is set, input parity checking is enabled. If INPCK is not set, input 
parity checking is disabled, allowing output parity generation without input 
parity errors. Note that whether input parity checking is enabled or disabled is 
independent of whether parity detection is enabled or disabled (see Control 
Modes §7.1.2.4). If parity detection is enabled but input parity checking is dis- 
abled, the hardware to which the terminal is connected shall recognize the par- 
ity bit, but the terminal special file shall not check whether this bit is set 
correctly or not. 

If ISTRIP is set, valid input bytes are first stripped to seven bits, otherwise all 
eight bits are processed. 

If INLCR is set, a received NL character is translated into a CR character. If 
IGNCR is set, a received CR character is ignored (not read). If IGNCR is not set 
and ICRNL is set, a received CR character is translated into a NL character. 

If IXON is set, start/stop output control is enabled. A received STOP character 
shall suspend output and a received START character shall restart output. 
When IXON is set, START and STOP characters are not read, but merely perform 
flow control functions. When IXON is not set, the START and STOP characters 
are read. 

If IXOFF is set, start/stop input control is enabled. The system shall transmit 
one or more STOP characters, which are intended to cause the terminal device to 
stop transmitting data, as needed to prevent the number of bytes in the input 
queue from exceeding {MAX_INPUT}, and shall transmit one or more START 
characters, which are intended to cause the terminal device to resume transmit- 
ting data, as soon as the device can continue transmitting data without risk of 
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overflowing the input queue. The precise conditions under which STOP and 
START characters are transmitted are implementation-defined. 
The initial input control value after open() is implementation-defined. 
7.1.2.3 Output Modes. Values of the c_oflag field describe the basic ter- 
minal output control, and are composed of the bitwise inclusive OR of the follow- 
ing masks, which shall be bitwise distinct: 


Mask Se 
ee Description 
OPOST Perform output processing. 


The mask name symbols for the c_oflag field are defined in <termios.h>. 

If OPOST is set, output data is processed in an implementation-defined 
fashion so that lines of text are modified to appear appropriately on the terminal 
device, otherwise characters are transmitted without change. 

The initial output control value after open() is implementation-defined. 

7.1.2.4 Control Modes. Values of the c_cflag field, shown in Table 7-3, 
describe the basic terminal hardware control, and are composed of the bitwise 
inclusive OR of the masks shown, which shall be bitwise distinct; not all values 
specified are required to be supported by the underlying hardware. The mask 
name symbols in this table are defined in <termios.h>. 


Table 7-3. termios c_cflag Field 


CLOCAL Ignore modem status lines. 
CREAD Enable receiver. 
CSIZE Number of bits per byte”: 
CS5 5 bits 
CS6 6 bits 
CS7 7 bits 
CS8 8 bits 
CSTOPB Send two stop bits, else one. 
HUPCE Hang up on last close. 
PARENB Parity enable. 
PARODD Odd parity, else even. 


The CSIZE bits specify the byte size in bits for both transmission and recep- 
tion. This size does not include the parity bit, if any. If CSTOPB is set, two stop 
bits are used, otherwise one stop bit. For example, at 110 baud, two stop bits 


* CSIZE has historically described “character” size. 


7.1 General Terminal Interface. Sy 


IEEE 
Std 1003.1-1988 IEEE STANDARD PORTABLE OPERATING SYSTEM 


are normally used. 

If CREAD is set, the receiver is enabled. Otherwise, no characters shall be 
received. 

If PARENB is set, parity generation and detection is enabled and a parity bit is 
added to each character. If parity is enabled, PARODD specifies odd parity if set, 
otherwise even parity is used. 

If HUPCL is set, the modem control lines for the port shall be lowered when 
the last process with the port open closes the port or the process terminates. 
The modem connection shall be broken. 

If CLOCAL is set, a connection does not depend on the state of the modem 
status lines. If CLOCAL is clear, the modem status lines shall be monitored. 

Under normal circumstances, a call to the open() function shall wait for the 
modem connection to complete. However, if the O_.NONBLOCK flag is set (see 
open() §5.3.1) or if CLOCAL has been set, the open() function shall return 
immediately without waiting for the connection. 

If the object for which the control modes are set is not an asynchronous serial 
connection, some of the modes may be ignored; for example, if an attempt is 
made to set the baud rate on a network connection to a terminal on another 
host, the baud rate may or may not be set on the connection between that termi- 
nal and the machine it is directly connected to. 

The initial hardware control value after open() is implementation-defined. 

7.1.2.5 Local Modes. Values of the c_lflag field, shown in Table 7-4, 
describe the control of various functions, and are composed of the bitwise 
inclusive OR of the masks shown, which shall be bitwise distinct. The mask 
name symbols in this table are defined in <termios.h>. 


Table 7-4. termios c_lflag Field 


Mask 
Name 


ECHO Enable echo. 

ECHOE Echo ERASE as an error-correcting backspace. 
ECHOK Echo KILL. 

ECHONL  Echo’\n’. 

ICANON Canonical input (erase and kill processing). 

IEXTEN Enable extended (implementation-defined) functions. 
ISIG Enable signals. 

NOFLSH __ Disable flush after interrupt, quit, or suspend. 
TOSTOP Send SIGTTOU for background output. 


Description 


If ECHO is set, input characters are echoed back to the terminal. If ECHO is 
not set, input characters are not echoed. 

If ECHOE and ICANON are set, the ERASE character shall cause the terminal 
to erase the last character in the current line from the display, if possible. If 
there is no character to erase, an implementation may echo an indication that 
this was the case or do nothing. 
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If ECHOK and ICANON are set, the KILL character shall either cause the ter- 
minal to erase the line from the display or shall echo the ’\n’ character after the 
KILL character. 

If ECHONL and ICANON are set, the ’\n’ character shall be echoed even if 
ECHO is not set. 

If ICANON is set, canonical processing is enabled. This enables the erase and 
kill edit functions, and the assembly of input characters into lines delimited by 
NL, EOF, and EOL, as described in Canonical Mode Input Processing 
§7.1.1.6. 

If ICANON is not set, read requests are satisfied directly from the input queue. 
A read shall not be satisfied until at least MIN bytes have been received or the 
timeout value TIME expired between bytes. The time value represents tenths of 
seconds. See the Non-Canonical Mode Input Processing §7.1.1.7 section for 
more details. 

If ISIG is set, each input character is checked against the special control char- 
acters INTR, QUIT, and SUSP Gob control only). If an input character matches 
one of these control characters, the function associated with that character is 
performed. If ISIG is not set, no checking is done. Thus these special input 
functions are possible only if ISIG is set. 

If IEXTEN is set, implementation-defined functions shall be recognized from 
the input data. It is implementation-defined how IEXTEN being set interacts 
with ICANON, ISIG, IXON, or IXOFF. If IEXTEN is not set, then 
implementation-defined functions shall not be recognized, and the correspond- 
ing input characters shall be processed as described for ICANON, ISIG, IXON, 
and IXOFF. 

If NOFLSH is set, the normal flush of the input and output queues associated 
with the INTR, QUIT, and SUSP (job control only) characters shall not be done. 

If TOSTOP is set and the implementation supports job control, the signal 
SIGTTOU is sent to the process group of a process that tries to write to its con- 
trolling terminal if it is not in the foreground process group for that terminal. 
This signal, by default, stops the members of the process group. Otherwise, the 
output generated by that process is output to the current output stream. 
Processes that are blocking or ignoring SIGTTOU signals are excepted and 
allowed to produce output and the SIGTTOU signal is not sent. 

The initial local control value after open() is implementation-defined. 

7.1.2.6 Special Control Characters. The special control characters 
values are defined by the array c_cc. The subscript name and description for 
each element in both canonical and non-canonical modes are shown in Table 7-5. 
The subscript name symbols in this table are defined in <termios.h>. 

The subscript values shall be unique, except that the VMIN and VTIME sub- 
scripts may have the same values as the VEOF and VEOL subscripts, respec- 
tively. 

Implementations that do not support job control may ignore the SUSP charac- 
ter value in the c_cc array indexed by the VSUSP subscript. 

The number of elements in the c_cc array, NCCS, is implementation-defined. 

Implementations which do not support changing the START and STOP charac- 
ters may ignore the character values in the c_cc array indexed by the VSTART 
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Table 7-5. termios c_cc Special Control Characters 


Subscript Usage 
Canonical Non-Canonical Bescnpenn 
Mode. =~ Mae 
VEOF EOF character 
VEOL EOL character 
VERASE ERASE character 
VINTR VINTR INTR character 
VKILL KILL character 
VMIN MIN value 
VQUIT VQUIT QUIT character 
VSUSP VSUSP SUSP character 
VTIME TIME value 
VSTART VSTART START character 
VSTOP VSTOP STOP character 


and VSTOP subscripts when tcsetatir() is called, but shall return the value in 
use when tcgetattr() is called. 

If { POSIX_VDISABLE} is defined for the terminal device file, and the value of 
one of the changeable special control characters (see Special Characters 
§7.1.1.9) is {_POSIX_VDISABLE}, that function shall be disabled; that is, no input 
data shall be recognized as the disabled special character. If ICANON is not set, 
the value of {_POSIX_VDISABLE} has no special meaning for the VMIN and 
VTIME entries of the c_cc array. 

The initial values of all control characters are implementation-defined. 

7.1.2.7 Baud Rate Functions. 
Functions: cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed () 
7.1.2.7.1 Synopsis. 


#include <termios.h> 
speed_t cfgetospeed (termios_p) 
struct termios *termios_p; 


int cfsetospeed (termios_p, speed) 
struct termios *termios_p; 
speed_t speed; 


speed_t cfgetispeed (termios_p) 
struct termios *termios_p; 


int cfsetispeed (termios_p, speed) 
struct termios *termios_p; 
speed_t speed; 
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7.1.2.7.2 Description. The following interfaces are provided for get- 
ting and setting the values of the input and output baud rates in the termios 
structure. The effects on the terminal device described below do not become 
effective until the tcsetattr() function is successfully called. 
The input and output baud rates are stored in the termios structure. The 
values shown in Table 7-6 are supported. The name symbols in this table are 
defined in <termios.h>. 


Table 7-6. termios Baud Rate Values 


Name Description Name __— Description 
BO Hang up B600 600 baud 
B50 50 baud B1200 1200 baud 
B75 75 baud B1800 1800 baud 
B110 110 baud B2400 2400 baud 
B134 1834.5 baud B4800 4800 baud 
B150 150 baud B9600 9600 baud 
B200 200baud B19200 19200 baud 
B300 300 baud B38400 38400 baud 


The type speed_t shall be defined in <termios.h> and shall be an unsigned 
integral type. 
The termios_p argument is a pointer to a termios structure. 
cfgetospeed() returns the output baud rate stored in the termios structure 
pointed to by termios_p. 
cfsetospeed() sets the output baud rate stored in the termios structure pointed 
to by termios_p to speed. The zero baud rate, BO, is used to terminate the con- 
nection. If BO is specified, the modem control lines shall no longer be asserted. 
Normally, this will disconnect the line. 
cfgetispeed() returns the input baud rate stored in the termios structure. 
cfsetispeed() sets the input baud rate stored in the termios structure to speed. 
If the input baud rate is set to zero, the input baud rate will be specified by the 
value of the output baud rate. Both cfsetispeed() and cfsetospeed() return a 
value of zero if successful and —1 to indicate an error. Attempts to set unsup- 
ported baud rates shall be ignored, and it is implementation-defined whether an 
error is returned by any or all of cfsetispeed(), cfsetospeed(), or tcsetattr(). This 
refers both to changes to baud rates not supported by the hardware, and to 
changes setting the input and output baud rates to different values if the 
hardware does not support this. 
7.1.2.7.3 Returns. See Description. 
7.1.2.7.4 Errors. This standard does not specify any error conditions 
that are required to be detected for the cfgetispeed(), cfgetospeed (), cfsetispeed(), 
or cfsetospeed() functions. Some errors may be detected under implementation- 
defined conditions. 
7.1.2.7.5 References. tcsetattr() §7.2.1. 
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7.2 General Terminal Interface Control Functions. The functions that 
are used to control the general terminal function are described in this section. 
If the implementation supports job control, unless otherwise noted for a specific 
command, these functions are restricted from use by background processes. 
Attempts to perform these operations shall cause the process group to be sent a 
SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, 
the process is allowed to perform the operation and the SIGTTOU signal is not 
sent. 

In all the functions, fildes is an open file descriptor. However, the functions 
affect the underlying terminal file, and not just the open file description associ- 
ated with the file descriptor. 


7.2.1 Get and Set State. 
Functions: tcgetattr(), tcsetattr( 
7.2.1.1 Synopsis. 


#include <termios.h> 


int tegetattr (fildes, termios_p) 
int fildes; 
struct termios *termios_p; 


int tesetattr (fildes, optional_actions, termios_p) 
int fildes, optional_actions; 
struct termios *termios_p; 


7.2.1.2 Description. The fcgetattr() function shall get the parameters 
associated with the object referred to by fildes and store them in the termios 
structure referenced by termios_p. This function is allowed from a background 
process; however, the terminal attributes may be subsequently changed by a 
foreground process. 

The tcsetattr() function shall set the parameters associated with the terminal 
(unless support is required from the underlying hardware that is not available) 
from the termios structure referenced by termios_p as follows: 

(1) If optional_actions is TCSANOW, the change shall occur immediately. 

(2) If optional_actions is TCSADRAIN, the change shall occur after all output 
written to fildes has been transmitted. This function should be used when 
changing parameters that affect output. 

(3) If optional_actions is TCSAFLUSH, the change shall occur after all output 
written to the object referred to by fildes has been transmitted, and all input 
that has been received but not read shall be discarded before the change is 
made. 

The symbolic constants for the values of optional_actions are defined in 
<termios.h>. 

7.2.1.3 Returns. Upon successful completion, a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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7.2.1.4 Errors. If any of the following conditions occur, the tcgetattr() 
function shall return —1 and set errno to the corresponding value: 

[EBADF] The fildes argument is not a valid file descriptor. 

[ENOTTY] The file associated with fildes is not a terminal. 

If any of the following conditions occur, the tcsetattr() function shall return —1 
and set errno to the corresponding value: 

[EBADF] The fildes argument is not a valid file descriptor. 

[EINVAL] The optional_actions argument is not a proper value, or an 
attempt was made to change an attribute represented in the ter- 
mios structure to an unsupported value. 

[ENOTTY] The file associated with fildes is not a terminal. 

7.2.1.5 References. <termios.h> §7.1.2. 


7.2.2 Line Control Functions. 
Functions: tcsendbreak(), tedrain(), tcflush(), tcflow() 
7.2.2.1 Synopsis. 


#include <termios.h> 


int tcsendbreak (fildes, duration) 
int fildes; 
int duration; 


int tedrain (fildes) 
int fildes; 


int tcflush (fildes, queuwe_selector) 
int fildes; 
int queue_selector; 


int tcflow (fildes, action) 
int fildes; 
int action; 


7.2.2.2 Description. If the terminal is using asynchronous serial data 
transmission, the tcsendbreak() function shall cause transmission of a continu- 
ous stream of zero-valued bits for a specific duration. If duration is zero, it shall 
cause transmission of zero-valued bits for at least 0.25 seconds, and not more 
that 0.5 seconds. If duration is not zero, it shall send zero-valued bits for an 
implementation-defined period of time. 

If the terminal is not using asynchronous serial data transmission, it is 
implementation-defined whether the tcsendbreak() function sends data to gen- 
erate a break condition (as defined by the implementation) or returns without 
taking any action. 

The tcdrain() function shall wait until all output written to the object referred 
to by fildes has been transmitted. 

The tcflush() function shall discard data written to the object referred to by 
fildes but not transmitted, or data received but not read, depending on the value 
of queue_selector: 
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(1) If queue_selector is TCIFLUSH, it shall flush data received but not read. 
(2) If queue_selector is TCOFLUSH, it shall flush data written but not 
transmitted. 
(3) If queue_selector is TCIOFLUSH, it shall flush both data received but not 
read, and data written but not transmitted. 
The tcflow() function shall suspend transmission or reception of data on the 
object referred to by fildes , depending on the value of action: 
(1) If action is TCOOFF, it shall suspend output. 
(2) If action is TCOON, it shall restart suspended output. 
(3) If action is TCIOFF, the system shall transmit a STOP character, which is 
intended to cause the terminal device to stop transmitting data to the sys- 
tem. (See the description of IXOFF in Input Modes §7.1.2.2.) 
(4) If action is TCION, the system shall transmit a START character, which is 
intended to cause the terminal device to start transmitting data to the sys- 
tem. (See the description of IXOFF in Input Modes $7.1.2.2.) 
The symbolic constants for the values of quewe_selector and action are defined 
in <termios.h>. 
The default on open of a terminal file is that neither its input nor its output is 
suspended. 
7.2.2.8. Returns. Upon successful completion, a value of zero is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 
7.2.2.4 Errors. If any of the following conditions occur, the tcsendbreak() © 
function shall return —1 and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[ENOTTY] The file associated with fildes is not a terminal. 
If any of the following conditions occur, the tcdrain() function shall return —1 
and set errno to the corresponding value: 
L[EBADF] The fildes argument is not a valid file descriptor. 
[EINTR] A signal interrupted the tcdrain() function. 
[ENOTTY] The file associated with fildes is not a terminal. 
If any of the following conditions occur, the tcflush() function shall return —1 
and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[EINVAL] The queue_selector argument is not a proper value. 
[ENOTTY]| The file associated with fildes is not a terminal. 
If any of the following conditions occur, the tcflow() function shall return —1 
and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[EINVAL] The action argument is not a proper value. 
[ENOTTY] The file associated with fildes is not a terminal. 
7.2.2.5 References. <termios.h> §7.1.2. 


138 Device- and Class-Specific Functions 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


7.2.3 Get Foreground Process Group ID. 
Function: tegetpgrp() 
7.2.3.1 Synopsis. 


#include <sys/types.h> 


pid_t tegetpgrp (fildes) 
int fildes; 


7.2.3.2 Description. 
If {_POSIX_JOB_CONTROL} is defined: 
(1) The tcgetpgrp() function shall return the value of the process 
group ID of the foreground process group associated with the termi- 
nal. 
(2) The tcegetpgrp() function is allowed from a process that is a 
member of a background process group; however, the information 
may be subsequently changed by a process that is a member of a 
foreground process group. 
Otherwise: 
The implementation shall either support the tcgetpgrp() function as 
described above, or the tcgetpgrp() call shall fail. 
7.2.3.3 Returns. Upon successful completion, tcgetpgrp() returns the 
process group ID of the foreground process group associated with the terminal. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 
7.2.3.4 Errors. If any of the following conditions occur, the tcgetpgrp() 
function shall return —1 and set errno to the corresponding value: 
[EBADF] The fildes argument is not a valid file descriptor. 
[ENOSYS] The tcgetpgrp() function is not supported in this implementa- 
tion. 
[ENOTTY] The calling process does not have a controlling terminal or the 
file is not the controlling terminal. 
7.2.3.5 References. setsid() §4.3.2, setpgid() §4.3.3, tcesetpgrp() §7.2.4. 


7.2.4 Set Foreground Process Group ID. 
Function: tcsetpgrp () 
7.2.4.1 Synopsis. 


#include <sys/types.h> 


int tesetpgrp (fildes, pgrp_id) 
int fildes; 
pid_t pgrp_id; 


7.2.4.2 Description. 
If {_ POSIX_JOB_CONTROL} is defined: 
If the process has a controlling terminal, the tcsetpgrp() function shall 
set the foreground process group ID associated with the terminal to 
pgrp_id. The file associated with fildes must be the controlling termi- 
nal of the calling process and the controlling terminal must be 
currently associated with the session of the calling process. The value 
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of pgrp_id must match a process group ID of a process in the same ses- 
sion as the calling process. 

Otherwise: 

The implementation shall either support the tcsetpgrp() function as 
described above, or the tcsetpgrp() call shall fail. 
7.2.4.3 Returns. Upon successful completion, tcsetpgrp() returns a value 
of zero. Otherwise, a value of —-1 is returned and errno is set to indicate the 
error. 
7.2.4.4 Errors. If any of the following conditions occur, the tcsetpgrp() 
function shall return —1 and set errno to the corresponding value: 

[EBADF] The fildes argument is not a valid file descriptor. 

[EINVAL] The value of the pgrp_id argument is a value not supported by 
the implementation. 

[ENOSYS] The tcsetpgrp() function is not supported in this implementa- 
tion. 

[ENOTTY] The calling process does not have a controlling terminal, or the 
file is not the controlling terminal, or the controlling terminal is 
no longer associated with the session of the calling process. 

[EPERM] The value of pgrp_id is a value supported by the implementa- 
tion but does not match the process group ID of a process in the 
same session as the calling process. 
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8.1 Referenced C Language Routines. The functions listed below will be 
described in the indicated sections of the C Standard. IEEE Std 1003.1-1988 
with the C Language Binding comprises these functions, the extensions to them 
described in this chapter, and the rest of the requirements stipulated in this 
standard. The functions appended with plus signs (+) have requirements 
beyond those set forth in the C Standard. Any implementation claiming confor- 
mance to IEEE Std 1003.1-1988 with the C Language Binding shall comply with 
the requirements outlined in this chapter, the requirements stipulated in the 
rest of this standard, and the requirements in the indicated sections of the 
C Standard. 

For requirements concerning conformance to this chapter, see Language- 
Dependent Services for the C Programming Language §2.2.3 and its sub- 
sections. 

4.2 Diagnostics 
Functions: assert. 

4.3 Character Handling 
Functions: isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, 
ispunct, isspace, isupper, isxdigit, tolower, toupper. 

4.4 Localization 
Functions: setlocale+. 

4.5 Mathematics 
Functions: acos, asin, atan, atan2, cos, sin, tan, cosh, sinh, tanh, exp, 
frexp, ldexp, log, log10, modf, pow, sqrt, ceil, fabs, floor, fmod. 

4.6 Non-Local Jumps 
Functions: setjmp, longjmp. 

4.9 Input/Output 
Functions: clearerr, fclose, feof, ferror, fflush, fgetc, fgets, fopen, fputc, 
fputs, fread, freopen, fseek, ftell, fwrite, getc, getchar, gets, perror, 
printf, fprintf, sprintf, putc, putchar, puts, remove, rename+, rewind, 
scanf, fscanf, sscanf, setbuf, tmpfile, tmpnam, ungetc. 

4.10 General Utilities 
Functions: abs, atof, atoi, atol, rand, srand, calloc, free, malloc, real- 
loc, abort+, exit, getenv+, bsearch, qsort. 

4.11 String Handling 
Functions: strcpy, strncpy, strcat, strncat, stremp, strnemp, strchr, 
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strespn, strpbrk, strrchr, strspn, strstr, strtok, strlen. 

4.12 Date and Time 
Functions: time, asctime, ctime+, gmtime+, localtime+, mktime+, 
strftime+. 

Systems conforming to the IEEE Std 1003.1-1988 shall make no distinction 
between the “text streams” and the “binary streams” described in the 
C Standard. 

For the fseek() function, if the specified position is beyond end-of-file, the 
consequences described in /seek() (see lseek() §6.5.3) shall occur. > 

The EXIT_SUCCESS macro, as used by the exit() function, shall evaluate to a 
value of zero. 

The relationship between a time in seconds since the Epoch used as an argu- 
ment to gmtime() and the tm structure (defined in <time.h>) is that the result 
shall be as specified in the expression given in the definition of seconds since 
the Epoch §2.3, where the names in the structure and in the expression 
correspond. If the time zone UCTO is in effect, this shall also be true for local- 
time() and mktime(). 


8.1.1 Extensions to Time Functions. The contents of the environment 
variable named TZ (see Environment Variables §2.7) shall be used by the 
functions ctime(), localtime(), strftime(), and mktime() to override the default 
time zone. The value of TZ has one of the two forms (spaces inserted for clarity): 


: characters 
or: 
std offset dst offset, rule 


If TZ is of the first format (i.e., if the first character is a colon), the characters 
following the colon are handled in an implementation-defined manner. 

The expanded format (for all TZs whose value does not have a colon as the 
first character) is as follows: 


stdoffset(dstloffset]|, start[/time], end[/time]]] 


Where: 

std anddst Three or more bytes that are the designation for the standard 
(std) or summer (dst) time zone. Only std is required; if dst is 
missing, then summer time does not apply in this locale. 
Upper- and lowercase letters are explicitly allowed. Any char- 
acters except a leading colon (:), digits, comma (,), minus (—), 
plus (+), and ASCII NUL are allowed. 

offset Indicates the value one must add to the local time to arrive at 
Coordinated Universal Time. The offset has the form: 


hhl:mmI{[:ss]l 


The minutes (mm) and seconds (ss) are optional. The hour (AA) 
shall be required and may be a single digit. The offset following 
std shall be required. If no offset follows dst, summer time is 
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assumed to be one hour ahead of standard time. One or more 
digits may be used; the value is always interpreted as a decimal 
number. The hour shall be between zero and 24, and the 
minutes (and seconds}—if present—between zero and 59. Out 
of range values may cause unpredictable behavior. If preceded 
by a “—”, the time zone shall be east of the Prime Meridian; oth- 
erwise it shall be west (which may be indicated by an optional 
preceding “+”). 

rule Indicates when to change to and back from summer time. The 
rule has the form: 


date/time ,date/time 


where the first date describes when the change from standard 
to summer time occurs and the second date describes when the 
change back happens. Each time field describes when, in 
current local time, the change to the other time is made. 

The format of date shall be one of the following: 

Jn The Julian day n (1 <n < 365). Leap days shall 
not be counted. That is, in all years—including 
leap years—February 28 is day 59 and March 1 is 
day 60. It is impossible to explicitly refer to the 


occasional February 29. 

n The zero-based Julian day (0 < n < 365). Leap 
days shall be counted, and it is possible to refer to 
February 29. 


Mm.n.d The d™® day (0 < d < 6) of week n of month m of 
the year (1 <n <5, 1<m ¥ 12, where week 5 
means “the last d day in month m” which may 
occur in either the fourth or the fifth week). 
Week 1 is the first week in which the d'th day 
occurs. Day zero is Sunday. 

The time has the same format as offset except that no leading 
sign (“—” or “+”) shall be allowed. The default, if time is not 
given, shall be 02:00:00. 

Whenever ctime(), strftime(), mktime(). or localtime() is called. the time zone 
names contained in the external variable tzmame shall be set as if the fzset() 
§$8.3.2 function had been called. 

Applications are explicitly allowed to change TZ and have the changed TZ 
apply to themselves. 
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8.1.2 Extensions to setlocale() Function. 
Function: setlocale() 
8.1.2.1 Synopsis. 


#include <locale.h> 


char *setlocale (category, locale) 
int category; 
char *locale; 


8.1.2.2 Description. The C Standard allows the specification of an 

implementation-defined native environment for the setlocale() function, which 
shall set a specific category to an implementation-defined default. For IEEE Std 
1003.1-1988 systems, this corresponds to the value of the environment vari- 
ables. 

A specific category may be set to an implementation-defined default value by 
passing the Jocale argument with a pointer to a null string. 

Possible values for category include: 


LC_CTYPE 

LC_COLLATE 

LC_TIME 

LC_NUMERIC 

LC_MONETARY 

Implementation-defined additional categories 


In all cases, setlocale() shall first check the value of the corresponding 
environment variable (for example, LC_CTYPE for the LC_CTYPE category) and 
if valid (.e., points to the name of a valid locale), setlocale() shall set the speci- 
fied category of the international environment to that value and return the 
string corresponding to the locale set (i.e., the value of the environment vari- 
able, not ""). If the value is invalid, setlocale() shall return a NULL pointer 
and the international environment is not changed by this function call. 

If the environment variable corresponding to the specified category is not set 
or is set to the empty string, the behavior of setlocale() is implementation- 
defined, unless the LANG environment variable is set and valid in which case 
setlocale() will set the category to the corresponding value of LANG. In some 
implementations, this may default to a system-wide value, others may default to 
the "C" locale. Setting all categories to the implementation-defined default is 
similar to the previous usage, but it interrogates all the environment variables 
to determine the specific value to set. To set all categories in the international 
environment, setlocale() is invoked in the following manner: 


Sic ereeLls (HO Tlie, 4!) 2 


To satisfy this request, setlocale() first checks all the environment variables. 
If any environment variable is invalid, setlocale() returns a null pointer and the 
international environment is not changed by this function call. If all the 
relevant environment variables are valid, setlocale() sets the international 
environment to reflect the values of the environment variables. The categories 
are set in the following order: 
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LC_CTYPE 

LC_COLLATE 

LC_TIME 

LC_NUMERIC 

LC_MONETARY 

Implementation-defined additional categories 


Using this scheme, the categories corresponding to the environment variables 
will override the value of the LANG environment variable for a particular 
category. 

If the LANG environment variable is not set or is set to the empty string, the 
behavior of 


setlocale (category, "") 
is implementation-defined. 


8.2 FILE-Type C Language Functions. This section describes functions 
which make reference to the FILE type, (as described in the C Standard), and 
their interactions with other functions defined by this standard. 

The terms file position indicator and stream are those defined by the 
C Standard. 

A stream is considered local to a single process. After a fork() call each of the 
parent and child have distinct streams which share an open file description. 


8.2.1 Map a Stream Pointer to a File Descriptor. 
Function: fileno() 
8.2.1.1 Synopsis. 


#include <stdio.h> 


int fileno (stream) 
FILE *stream; 


8.2.1.2 Description. The fileno() function returns the integer file 
descriptor associated with the stream (see open() §5.3.1). 
The following symbolic values in <unistd.h> §2.10 define the file descriptors 
that shall be associated with the C language stdin, stdout, and stderr when the 
application is started: 


Name Description Value 
STDIN_FILENO Standard input value, stdin. 0 
STDOUT_FILENO Standard output value, stdout. 1 
STDERR_FILENO Standard error value, stderr. 2 


8.2.1.3 Returns. See Description. If an error occurs, a value of —1 is 
returned and errno is set to indicate the error. 
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8.2.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the fileno() function. Some errors may be 
detected under implementation-defined conditions. 

8.2.1.5 References. open() §5.3.1. 


8.2.2 Open a Stream on a File Descriptor. 
Function: fdopen() 
8.2.2.1 Synopsis. 


#include <stdio.h> 


FILE «fdopen (fildes, type) 
int fildes; 
char *type; 


8.2.2.2 Description. The fdopen() routine associates a stream with a file 
descriptor. 
The type argument is a character string having one of the following values: 


ye open for reading 

my open for writing 

a" open for writing at end-of-file 

"r+" open for update (reading and writing) 

"wt" open for update (reading and writing) 

"a+" open for update (reading and writing) at end-of-file 


The meaning of these flags is exactly as specified by the C Standard for 
fopen(), except that "w" and "w+" do not cause truncation of the file. Addi- 
tional values for the type argument may be defined by an implementation. 

The type of the stream must be allowed by the mode of the open file. 

The file position indicator associated with the new stream is set to the posi- 
tion indicated by the file offset associated with the file descriptor. 

fdopen() may cause the st_atime field of the underlying file to be marked for 
update. 

8.2.2.3 Returns. If successful, the fdopen() function returns a pointer to 
a stream. Otherwise, a NULL pointer is returned and errno is set to indicate the 
error. 

8.2.2.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the fdopen() function. Some errors may be 
detected under implementation-defined conditions. 

8.2.2.5 References. open() §5.3.1, fopen() (C Standard). 


8.2.3 Interactions of Other FILE-Type C Functions. A single open file 
description can be accessed both through streams and through file descriptors. 
Either a file descriptor or a stream will be called a handle on the open file 
description to which it refers; an open file description may have several handles. 

Handles can be created or destroyed by user action, without affecting the 
underlying open file description. Some of the ways to create them include 
fentl(), dup(), fdopen(), fileno(), and fork() (which duplicates existing ones into 
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new processes). They can be destroyed by at least fclose(), close(), and the exec 
functions (which close some file descriptors, and destroy streams). 

A file descriptor which is never used in an operation that could affect the file 
offset (for example read(), write(), or lseek()) is not considered a handle in this 
discussion, but could give rise to one (as a consequence of fdopen(), dup(), or 
fork(), for example). This exception does include the file descriptor underlying a 
stream, whether created with fopen() or fdopen(), as long as it is not used 
directly by the application to affect the file offset. (The read() and write() func- 
tions implicitly affect the file offset; Jseek() explicitly affects it.) 

The result of function calls involving any one handle (the active handle) are 
defined elsewhere in this standard, but if two or more handles are used, and any 
one of them is a stream, their actions shall be coordinated as described below. If 
this is not done, the result is undefined. 

A handle which is a stream is considered to be closed when either an fclose() 
or freopen() is executed on it (the result of freopen() is a new stream for this dis- 
cussion, which cannot be a handle on the same open file description as its previ- 
ous value), or when the process owning that stream terminates with exit() or 
abort(). A file descriptor is closed by close(), _exit(), or by one of the exec func- 
tions when FD_CLOEXEC is set on that file descriptor. 

For a handle to become the active handle, the actions below must be per- 
formed between the last other use of the first handle (the current active handle) 
and the first other use of the second handle (the future active handle). The 
second handle then becomes the active handle. All activity by the application 
affecting the file offset on the first handle shall be suspended until it again 
becomes the active handle. (If a stream function has as an underlying function 
which affects the file offset, the stream function will be considered to affect the 
file offset. The underlying functions are described below.) 

The handles need not be in the same process for these rules to apply. 

(1) For the first handle, the first applicable condition below shall apply. 
After the actions required below are taken, if the handle is still open, it may 
be closed. 
(a) If it is a file descriptor, no action is required. 
(b) If the only further action to be performed on any handle to this open 
file description is to close it, no action need be taken. 
(c) If it is a stream which is unbuffered, no action need be taken. 
(d) If it is a stream which is line-buffered, and the last operation had the 
same effect on the underlying file as a fgets() or fputs(), no action need be 
taken. In the case of an fgets(), the effect above is to be interpreted as if 
no readahead that the implementation may choose to do had actually 
occurred. 
(e) If it is a stream which is open for writing or append, (but not also open 
for reading) either a fflush() shall occur or the stream shall be closed. 
(f) If the stream is open for reading and it is at the end of the file (feof() is 
true), no action need be taken. 
(g) If the stream is open with a mode that allows reading and the underly- 
ing open file description refers to a device that is capable of seeking, 
either a fflush() shall occur or the stream shall be closed. 
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(h) Otherwise, the result is undefined. 
(2) For the second handle: if any previous active handle has called a function 
that explicitly changed the file offset, except as required above for the first 
handle, the application shall perform an /seek() or fseek() (as appropriate to 
the type of the handle) to an appropriate location. 
(3) If the active handle ceases to be accessible before the requirements on the 
first handle above have been met, the state of the open file description 
becomes undefined. This might occur, for example, during a fork() or _exit(). 
(4) The exec functions shall be considered to make inaccessible all streams 
which are open at the time they are called, independent of what streams or 
file descriptors may be available to the new process image. 
(5) Implementations shall assure that an application, even one consisting of 
several processes, shall yield correct results (no data is lost or duplicated 
when writing, all data is written in order, except as requested by seeks, and 
all data is seen on reading sequentially) when the rules above are followed, 
regardless of the sequence of handles used. If the rules above are not fol- 
lowed, the result is unspecified. 
(6) Each function that operates on a stream is said to have zero or more 
underlying functions. This means that the stream function shares certain 
traits with the underlying functions, but does not require that there be any 
relation between the implementations of the stream function and its under- 
lying functions. 
(7) Also, in the sections below, additional requirements on the standard I/O 
routines, beyond those in the C Standard, are given. 
8.2.3.1 fopen(). fopen() shall allocate a file descriptor as open() does. 
fopen() may cause the st_atime field of the underlying file to be marked for 
update. 

The underlying function is open(). 

8.2.3.2 fclose(). fclose() shall perform a close() on the file descriptor that 
is associated with the FILE stream. It shall also mark for update the st_ctime 
and st_mtime fields of the underlying file, if the stream was writable, and if buf- 
fered data had not been written to the file yet. 

The underlying functions are write() and close(). 

If the file is not already at EOF, and the file is one capable of seeking, the file 
offset of the underlying open file description shall be adjusted so that the next 
operation on the open file description deals with the byte after the last one read 
from or written to the stream being closed. 

8.2.3.3 freopen(). freopen() has the properties of both fclose() and fopen(). 

8.2.3.4 fflush(). fflush( shall mark for update the st_ctime and st_mtime 
fields of the underlying file if the stream was writable and if buffered data had 
not been written to the file yet. 

The underlying functions are read(), write(), and lseek(). 

If the stream is open for reading, any unread data buffered in the stream 
shall be invalidated. 

For a stream open for reading, if the file is not already at EOF, and the file is 
one capable of seeking, the file offset of the underlying open file description 
shall be adjusted so that the next operation on the open file description deals 
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with the byte after the last one read from or written to the stream being closed. 

8.2.3.5 fgetc(, fgets(, fread(), getc(), getchar(), gets(), scanf(), fscanf(. 
These functions may mark the st_atime field for update. The st_atime field 
shall be marked for update by the first successful execution of one of these func- 
tions that returns data not supplied by a prior call to ungetc(). 

The underlying functions are read() and Iseek(). 

8.2.3.6 fputcQ, fputs(), fwriteQ, putcQ, putcharQ), puts(), printfQO, 
uprint{(), ufprintfQ. The st_ctime and st_mtime fields of the file shall be 
marked for update between the successful execution of one of these functions 
and the next successful completion of a call to either fflush() or fclose() on the 
same stream or a call to exit() or abort(). 

The underlying functions are write() and /seek(). 

8.2.3.7 fseek(), rewind(). These functions shall mark the st_ctime and 
st_mtime fields of the file for update if the stream was writable and if buffered 
data had not yet been written to the file. 

The underlying functions are /seek() and write(). 

If the most recent operation, other than ftell(), on a given stream is fflush(), 
the file offset in the underlying open file description shall be adjusted to reflect 
the location specified by the fseek(). 

8.2.3.8 perror(). This function shall mark the file associated with the 
standard error stream as having been written (st_ctime, st_mtime marked for 
update) at some time between its successful completion and the completion of 
fflush() or fclose() on stderr, or exit() or abort(). 

8.2.3.9 tmpfile(). tmpfile() shall allocate a file descriptor as fopen() does. 

8.2.3.10 ftellQ. The underlying function is fseek(). The result of ftell() 
after an fflush() shall be the same as the result before the fflush(). 

8.2.3.11 Error Reporting. If any of the functions above return an error 
indication caused by a condition that would be detected by the corresponding 
underlying functions listed above, the value returned in errno shall be the one 
provided for the underlying function. 

8.2.3.12 exit(), abort(). The exit() function shall have the effect of fclose () 
on every open stream, with the properties of fclose() as described above. The 
abort() function shall also have these effects if the call to abort() causes pro- 
gram termination (see the C Standard for the conditions where program termi- 
nation will not occur.) 


8.2.4 Operations on Files — the remove() Function. The remove() func- 
tion shall have the same effect on file times as wnlink(). 
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8.3 Other C Language Functions. 


8.3.1 Non-Local Jumps. 
Functions: sigsetjmp(), siglongjmp() 
8.3.1.1 Synopsis. 


#include <setjmp.h> 


int sigsetjmp (env, savemask ) 
sigjmp_buf env; 
int savemask; 


void siglongjmp (env, val) 
sigjmp_buf env; 
int val; 


8.3.1.2 Description. The sigsetjmp() macro shall comply with the defini- 
tion of the setjmp() macro in the C Standard. If the value of the savemask argu- 
ment is not zero, the sigsetjmp() function shall also save the process’s current 
signal mask (see <signal.h> §3.3.1) as part of the calling environment. 

The siglongjmp() function shall comply with the definition of the longjmp() 
function in the C Standard. If and only if the env argument was initialized by a 
call to the sigsetjmp() function with a non-zero savemask argument, the 
siglongjmp() function shall restore the saved signal mask. 

8.3.1.3 References. sigaction() §3.3.4, <signal.h> §3.3.1, sigprocmask () 
$30.0, SISSUSpeEnd (Sarat. 


8.3.2 Set Time Zone. 
Function: ftzset() 
8.3.2.1 Synopsis. 


#include <time.h> 
void tzset () 


8.3.2.2. Description. The tzset() function uses the value of the environ- 
ment variable TZ to set time conversion information used by localtime(), 
ctime(), strftime(), and mktime(). If TZ is absent from the environment, 
implementation-defined default time zone information shall be used. 
The tzset() function shall set the external variable tzname: 


extern char *tzmameie je— ee ra Cosh 


where std and dst are as described in Extensions to Time Functions 88.1.1. 
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9. System Databases 


9.1 System Databases. The routines described in this section allow an appli- 
cation to access the two system databases that are described below. 
The group database contains the following information for each group: 
(1) group name 
(2) numerical group ID 
(3) list of the names or numbers of all users allowed in the group 
The user database contains the following information for each user: 
(1) login name 
(2) numerical user ID 
(3) numerical group ID 
(4) initial working directory 
(5) initial user program 
If the initial user program field is null, the system default is used. 
If the initial working directory field is null, the interpretation of that field is 
implementation-defined. 
These databases may contain other fields that are implementation-defined. 


9.2 Database Access. 


9.2.1 Group Database Access. 
Functions: getgrgid(), getgrnam() 
9.2.1.1 Synopsis. 


#include <grp.h> 


struct group *«getgrgid (gid) 
gid_t gid; 

struct group «getgrnam (name) 
char «name; 


9.2.1.2 Description. The getgrgid() and getgrnam() routines both return 
pointers to an object of type struct group containing an entry from the group 
database with a matching gid or name. This structure, which is defined in 
<grp.h>, includes the members shown in Table 9-1. 
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Table 9-1. group Structure 


Member Member 


Type Name 
char * gr_name 
gid_t gr_gid 


char **  gr_mem 


Description 


The name of the group. 

The numerical group ID. 

A null-terminated vector of pointers to 
the individual member names. 


9.2.1.3 Returns. A NULL pointer is returned on error or if the requested 


entry is not found. 


The return values may point to static data that is overwritten by each call. 
9.2.1.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the getgrgid() or getgrnam() functions. Some 
errors may be detected under implementation-defined conditions. 
9.2.1.5 References. getlogin() §4.2.4. 


9.2.2 User Database Access. 
Functions: getpwuid(), getpwnam() 


9.2.2.1 Synopsis. 
#include <pwd.h> 


struct passwd *getpwuid (uid) 


uid_t uid; 


struct passwd *getpwnam (name) 


char *name; 


9.2.2.2 Description. The getpwuid() and getpwnam() functions both 
return a pointer to an object of type struct passwd containing an entry from the 
user database with a matching wid or name. This structure, which is defined in 
<pwd.h>, includes the members shown in Table 9-2. 


Table 9-2. passwd Structure 


Member Member 


aoe Nae Description 
char * pw_name_ User’s login name. 
uid_t pw_uid User ID number. 
gid_t pw_gid Group ID number. 
char * pw_dir Initial Working Directory. 
char * pw_shell Initial User Program. 


The implementation of the cuserid() §4.2.4 function may use the getpwnam() 
function; thus the results of a user’s call to either routine may be overwritten by 
a subsequent call to the other routine. 
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9.2.2.3 Returns. A NULL pointer is returned on error or if the requested 
entry is not found. 
The return values may point to static data that is overwritten on each call. 
9.2.2.4 Errors. This standard does not specify any error conditions that 
are required to be detected for the getpwuid() or getpwnam() functions. Some 
errors may be detected under implementation-defined conditions. 
9.2.2.5 References. cuserid() §4.2.4, getlogin() §4.2.4. 
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10. Data Interchange Format 


10.1 Archive/Interchange File Format. A conforming system shall provide 
a mechanism to copy files from a medium to the file hierarchy and copy files 
from the file hierarchy to a medium using the interchange formats described 
here. This standard does not define this mechanism.* 

When this mechanism is used to copy files from the medium by a process 
without appropriate privileges, the protection information (ownership and 
access permissions) shall be set in the same fashion that creat() §5.3.2 would 
when given the mode argument matching the file permissions supplied by the 
mode field of extended tar format or the c_mode field of the extended cpio for- 
mat. A process with appropriate privileges shall restore the ownership and per- 
missions exactly as recorded on the medium, except that the symbolic user and 
group IDs are used for the tar format, as described in Extended tar Format 
SHG. 1: 

The format-creating utility is used to translate from the file system to the for- 
mats defined in this section, in an implementation-defined way, and the 
format-reading utility is used to translate from the formats defined in this sec- 
tion to a file system. 

The headers of these formats are defined to use characters represented in 
ASCII, however, no restrictions are made about the contents of the files them- 
selves. The data in a file may be binary data, or text represented in any format 
available to the user. When these formats are used to transfer text at the 
source level all characters shall be represented in ASCII. 


10.1.1 Extended tar Format. An extended tar archive tape or file con- 
tains a series of blocks. Each block is a fixed size block of 512 bytes (see below). 
Although this format may be thought of as being stored on 9-track industry 
standard inch magnetic tape, other types of transportable media are not 
excluded. Each file archived is represented by a header block that describes the 
file, followed by zero or more blocks that give the contents of the file. At the end 
of the archive file are two blocks filled with binary zeroes, interpreted as an 
end-of-archive indicator. 


* The 1003.2 Working Group is working on this mechanism. See Shell and Utilities §A.2.3. 
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The blocks may be grouped for physical I/O operations. Each group of n blocks 
(where n is set by the application utility creating the archive file) may be writ- 
ten with a single write() operation. On magnetic tape, the result of this write is 
a single tape record. The last group of blocks is always at the full size, so blocks 
after the two zero blocks contain undefined data. 

The header block is structured as shown in Table 10-1. All lengths and offsets 
are in decimal. 


Table 10-1. tar Header Block 


Field Name Byte Offset Length (in bytes) 
name 0 100 
mode 100 8 
uid 108 8 
gid 116 8 
size 124 iz 
mtime 136 1 
chksum 148 8 
typeflag 156 1 
linkname lis)// 100 
magic 257 6 
version 263 2 
uname 265 32 
gname Zor, 32 
deumajor 329 8 
deuvminor 3am 8 
prefix 345 155 


Symbolic constants used in the header block are defined in the header 
<tar.h> as follows: 


Fdefine TMAGICG. “ustar’ / = ustareaong samen Olea 


#define TMAGLEN 6 
#define TVERSION "OOM j* 010 and ner null 
#define TVERSLEN Z 


/* Values used in typeflag field */ 


#define REGTYPE no /* Regular file */ 
#define AREGTYPE NO J/* Regular fille 7 
#define LNKTYPE si as fe Vnaiguk x / 
#define SYMTYPE oe /* Reserved x / 
#define CHRTYPE ee /* Character special */ 
#define BLKTYPE “ae /* Block special */ 
#define DIRTYPE Se /* Direcrony 7 
#define FIFOTYPE "6" /* FIFO special */ 
#define CONTTYPE a /* Reserved x / 

/* Bits used in the mode field - values in octal */ 
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#define TSUID 04000 / See Ulpwon execution */ 
#define TSGID 020100 /* Set GID on execution */ 
#define TSVTX (Oe eeKe) /* Reserved */ 

/* File permissions */ 
#define TUREAD 00 400 /* read by owner */ 
#define TUWRITE 00200 /* write by owner */ 
#define TUEXEC 00100 /* execute/search by owner */ 
#define TGREAD 00040 /* read by group */ 
#define TGWRITE COZ © /* Wielte byegroup *~/ 
#define TGEXEC CxO) /* execute/search by group */ 
#define TOREAD 00004 Vom seerevcl Joy) onelovenc 4 / 
#define TOWRITE 00002 /* Were by sothorac, 
#define TOEXEC OG (Coa /* execute/search by other */ 
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All characters are represented in the American Standard Code for Informa- 
tion Interchange, ASCII. For maximum portability between implementations, 
names should be selected from characters represented by the portable 
filename character set §2.3 as 8-bit characters with zero parity. If an 
extended character set beyond the portable character set is used, and the 
format-reading and format-creating utilities on the two distinct systems use the 
same extended character set, the file name shall be preserved. However, the 
format-reading utility shall never create file names on the local system that can- 
not be accessed via the functions described previously in this standard; see 
open() §5.3.1, stat() §5.6.2, chdir() §5.2.1, fentl(Q) §6.5.2, and opendir() §5.1.2. If 
a file name is found on the medium that would create an invalid file name, the 
implementation shall define if the data from the file is stored on the file hierar- 
chy and under what name it is stored. A format-reading utility may choose to 
ignore these files as long as it produces an error indicating that the file is being 
ignored. 

Each field within the header block is contiguous; that is, there is no padding 
used. Each character on the archive medium is stored contiguously. 

The fields magic, uname, and gname are null-terminated character strings. 
The fields name, linkname, and prefix are null-terminated character strings 
except when all characters in the array contain non-null characters including 
the last character. The version field is two bytes containing the characters 
"00" (zero-zero). The typeflag contains a single character. All other fields are 
leading zero-filled octal numbers in ASCII. Each numeric field is terminated by 
one of more space or null characters. : 

The name and the prefix fields produce the pathname of the file. The 
hierarchical relationship of the file is retained by specifying the pathname as a 
path prefix, a slash character and filename as the suffix. If the prefix contains 
non-null characters, prefix, a slash character, and name are concatenated 
without modification or addition of new characters to produce a new pathname. 
In this manner, pathnames of at most 256 characters can be supported. If a 
pathname does not fit in the space provided, the format-creating utility shall 
notify the user of the error, and no attempt shall be made by the format-creating 
utility to store any part of the file, header or data, on the medium. 
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The linkname field, described below, does not use the prefix to produce a path- 
name. As such, a linkname is limited to 99 characters. If the name does not fit 
in the space provided, the format-creating utility shall notify the user of the 
‘error, and the utility shall not attempt to store the link on the medium. 

The mode field provides 9 bits specifying file permissions and 3 bits to specify 
the set UID, set GID, and TSVTX modes. Values for these bits were defined pre- 
viously. When appropriate privilege is required to set one of these mode bits, 
and the user restoring the files from the archive does not have the appropriate 
privilege, the mode bits for which the user does not have appropriate privilege 
shall be ignored. Some of the mode bits in the archive format are not mentioned 
elsewhere in this standard. If the implementation does not support those bits, 
they may be ignored. 

The wid and gid fields are the user and group ID of the file’s owner and group, 
respectively. 

The size field is the size of the file in bytes. If the typeflag field is set to 
specify a file to be of type LNKTYPE or SYMTYPE the size field shall be specified 
as zero. If the typeflag field is set to specify a file of type DIRTYPE the size field 
is interpreted as described under the definition of that record type. If the 
typeflag field is set to CHARTYPE, BLKTYPE, or FIFOTYPE the meaning of the 
size field is implementation-defined and no data blocks are stored on the 
medium. If the typeflag field is set to any other value, the number of blocks 
written following the header is (size +511)/512 ignoring any fraction in the result 
of the division. 

The mtime field is the modification time of the file at the time it was archived. 
It is the ASCII representation of the octal value of the modification time 
obtained from the stat() function. 

The chksum field is the ASCII representation of the octal value of the simple 
sum of all bytes in the header block. Each 8-bit byte in the header is treated as 
an unsigned value. These values are added to an unsigned integer, initialized to 
zero, the precision of which shall be no less than 17 bits. When calculating the 
checksum, the chksum field is treated as if it were all blanks. 

The typeflag field specifies the type of file archived. If a particular implemen- 
tation does not recognize the type, or the user does not have appropriate 
privilege to create that type, the file shall be extracted as if it were a regular file 
if the file type is defined to have a meaning for the size field that could cause 
data blocks to be written on the medium (see the previous description for size ). 
If conversion to an ordinary file occurs, the format-reading utility shall produce 
an error indicating that the conversion took place. 

ASCII digit ’0’ represents a regular file. For backward compatibility, a 
typeflag value of binary zero (‘\0’) should be recognized as 
meaning a regular file when extracting files from the archive. 
Archives written with this version of the archive file format 
shall create regular files with a typeflag value of ASCII ’0’. 

ASCII digit ’1’ represents a file linked to another file, of any type, previously 
archived. Such files are identified by each file having the 
same device and file serial number. The linked-to name is 
specified in the linkname field with a trailing null. 
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ASCII digit ‘2’ is reserved to represent a link to another file, of any type, 
whose device or file serial number differs. This is provided 
for systems that support linked files whose device or file 
serial numbers differ, and should be treated as a type ’1’ file 
if this extension does not exist. 

ASCII digits ‘3’ and ’4’ represent character special files and block special 
files respectively. In this case the devumajor and devminor 
fields shall contain implementation-defined information 
defining the device. Implementations may map the device 
specifications to their own local specification, or may ignore 
the entry. 

ASCII digit ’5’ specifies a directory or sub-directory. On systems where disk 
allocation is performed on a directory basis the size field shall 
contain the maximum number of bytes (which may be 
rounded to the nearest disk block allocation unit) that the 
directory may hold. A size field of zero indicates no such lim- 
iting. Systems that do not support limiting in this manner 
should ignore the size field. 

ASCII digit 6’ specifies a FIFO special file. Note that the archiving of a FIFO 
file archives the existence of this file and not its contents. 

ASCII digit ’7’ is reserved to represent a file to which an implementation has 
associated some high performance attribute. Implementa- 
tions without such extensions should treat this file as a regu- 
lar file (type ’0’). 

ASCII letters ‘A’ through ’Z’ are reserved for custom implementations. All 
other values are reserved for specification in future revisions 
of the standard. 

The magic field is the specification that this archive was output in this 
archive format. If this field contains TMAGIC, the uname and gname fields shall 
contain the ASCII representation of the owner and group of the file respectively 
(truncated to fit, if necessary). When the file is restored by a privileged, 
protection-preserving version of the utility, the password and group files shall 
be scanned for these names. If found, the user and group IDs contained within 
these files shall be used rather than the values contained within the uid and gid 
fields. 

The encoding of the header is designed to be portable across machines. 

10.1.1.1 References. <grp.h> §9.2.1, <pwd.h> §9.2.2, <sys/stat.h> 
§5.6.1, stat() §5.6.2, <unistd.h> §2.10. 


10.1.2 Extended cpio Format. The byte-oriented cpio archive format is 
a series of entries, each comprised of a header that describes the file, the name 
of the file, and then the contents of the file. 

An archive may be recorded as a series of fixed size blocks of bytes. This 
blocking shall be used only to make physical I/O more efficient. The last group 
of blocks is always at the full size. 

For the byte-oriented cpio archive format, the individual entry information 
must be in the order indicated and described by Table 10-2. 
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Table 10-2. Byte-Oriented cpio Archive Entry 


Header 

Field Name Length (in bytes) _Interpreted as_ 
c_magic 6 octal number 
c_dev 6 octal number 
c_ino 6 octal number 
c_mode 6 octal number 
c_uid 6 octal number 
c_gid 6 octal number 
c_nlink 6 octal number 
c_rdev 6 octal number 
c_mtime We octal number 
c_namesize 6 octal number 
c_filesize 11 octal number 

File Name 
Field Name _ Length __—__Interpreted as_ 
c_name c_namesize pathname string 

File Data 
Field Name Length Interpreted as 
c_filedata c_filesize data 


10.1.2.1 Header. For each file in the archive, a header as defined previ- 

ously shall be written. The information in the header fields shall be written as 
streams of ASCII characters interpreted as octal numbers. The octal numbers 
are extended to the necessary length by appending ASCII zeros at the most- 
significant digit end of the number; the result is written to the stream of bytes 
most significant digit first. The fields shall be interpreted as follows: 

(1) c_magic shall identify the archive as being a transportable archive by 

containing the magic bytes as defined by MAGIC (070707). 

(2) c_dev and c_ino shall contain values which uniquely identify the file 

within the archive (i.e., no files shall contain the same pair of c_dev and 

c_ino values unless they are links to the same file). The values shall be 

determined in an implementation-defined manner. 

(3) c_mode shall contain the file type and access permissions as defined in 

the tables below. 

(4) c_uid shall contain the user ID of the owner. 

(5) c_gid shall contain the group ID of the group. 

(6) c_nlink shall contain the number of links referencing the file at the time 

the archive was created. 

(7) c_rdev shall contain implementation-defined information for character or 

block special files. 

(8) c_mtime shall contain the latest time of modification of the file at the time 

the archive was created. 
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(9) c_namesize shall contain the length of the pathname, including the ter- 

minating null byte. 

(10) c_filesize shall contain the length of the file in bytes. This is the length 

of the data section following the header structure. 

10.1.2.2 File Name. c_name shall contain the pathname of the file. The 

length of this field in bytes is the value of c_namesize. If a file name is found on 
the medium that would create an invalid pathname, the implementation shall 
define if the data from the file is stored on the file hierarchy and under what 
name it is stored. 

All characters are represented in ASCII. For maximum portability between 
implementations, names should be selected from characters represented by the 
portable filename character set §2.3 as 8-bit characters with zero parity. If 
an extended character set beyond the portable character set is used, and the 
format-reading and format-creating utilities on the two distinct systems use the 
same extended character set, the file name shall be preserved. However, the 
format-reading utility shall never create file names on the local system that can- 
not be accessed via the functions described previously in this standard; see 
open() §5.3.1, stat() §5.6.2, chdir() §5.2.1, fentl() §6.5.2, and opendir() §5.1.2. If 
a file name is found on the medium that would create an invalid file name, the 
implementation shall define if the data from the file is stored on the local file 
system and under what name it is stored. A format-reading utility may choose 
to ignore these files as long as it produces an error indicating that the file is 
being ignored. 

10.1.2.8 File Data. Following c_name, there shall be c_filesize bytes of 
data. Interpretation of such data shall occur in a manner dependent on the file. 
If c_filesize is zero, no data shall be contained in c_filedata. 

10.1.2.4 Special Entries. FIFO special files, directories, and the trailer 
are recorded with c_filesize equal to zero. For other special files, c_filesize is 
implementation-defined. The header for the next file entry in the archive shall 
be written directly after the last byte of the file entry preceding it. A header 
denoting the file name “TRAILER! !!” shall indicate the end of the archive; the 
contents of bytes in the last block of the archive following such a header are 
undefined. 

10.1.2.5 cpio Values. Values needed by the cpio archive format are 
described in Table 10-3. 

C_ISDIR, C_ISFIFO, and C_ISREG shall be supported on an IEEE Std 1003.1- 
1988 conforming system; additional values defined previously are reserved for 
compatibility with existing systems. Additional file types may be supported; 
however, such files should not be written on archives intended for transport to 
portable systems. 

C_ISVTX, C_ISCTG, C_ISLNK, and C_ISSOCK have been reserved by this stan- 
dard to retain compatibility with some existing implementations. 

When restoring from an archive: 

(1) If the user does not have the appropriate privilege to create a file of the 
specified type, the format interpreting utility shall ignore the entry, and 
issue an error to the standard error output. 

(2) Only regular files have data to be restored. Presuming a regular file 
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Table 10-3. Values for cpio c_mode Field 


File Permissions 


_Name Value Indicates 

C_IRUSR 000400 # Read by owner 

C_IWUSR 000200 Write by owner 

C_IXUSR 000100 Execute by owner 

C_IRGRP 000040 Read by group 

C_IWGRP 000020 #£Write by group 

C_IXGRP 000010 Execute by group 

C_IROTH 000004 #Read by others 

C_LIWOTH 000002 # Write by others 

C_IXOTH 000001 Execute by others 

C_ISUID 004000 Set uid 

C_ISGID 002000 Set gid 

C_ISVTX 001000 # Reserved 

File Type 

Name Value Indicates 
C_ISDIR 040000  =—Directory 
C_ISFIFO 010000 FIFO 
C_ISREG 0100000 Regular file 
C_ISBLK 060000 _ Block special file 
C_ISCHR 020000 Character special file 
C_ISCTG 0110000 Reserved 
C_ISLNK 0120000 Reserved 
C_ISSOCK 0140000 Reserved 


meets any selection criteria that might be imposed on the format-reading 
utility by the user, such data shall be restored. 
(3) If a user does not have appropriate privilege to set a particular mode flag, 
the flag shall be ignored. Some of the mode flags in the archive format are 
not mentioned elsewhere in this standard. If the implementation does not 
support those flags, they may be ignored. 

10.1.2.6 References. <grp.h> §9.2.1, <pwd.h> §9.2.2, <sys/stat.h> 

§5.6.1, chmod() §5.6.4, link() §5.3.4, mkdir() §5.4.1, read() §6.4.1, stat() §5.6.2. 


10.1.3 Multiple Volumes. It shall be possible for data represented by the 
Archive/Interchange File Format to reside in more than one file. 

The format is considered a stream of bytes. An end-of-file (or equivalently an 
end-of-media) condition may occur between any two bytes of the logical byte 
stream. If this condition occurs, the byte following the end-of-file will be the 
first byte on the next file. The format-reading utility shall, in an 
implementation-defined manner, determine what file to read as the next file. 
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(These appendices are not a part of IEEE Std 1003.1-1988, IEEE Standard Portable Operating Sys- 
tem Interface for Computer Environments, but are included for information only.) 


A. Related Standards 


This appendix describes other standards efforts, related to IEEE Std 1003.1- 
1988, that are available or under development. 


A.1 Related Standards—Open System Environment. This IEEE Std 
1003.1-1988 is intended to complement others that together would provide a 
comprehensive Open System Environment. The standards in these areas fall 
into three areas: ones directly related to the IEEE Std 1003.1-1988, ones already 
available and of use to those interested in Open Systems Environments, and 
finally, those in development. 

IEEE and ANSI/IEEE standards can be ordered from: 


Publication Sales 

IEEE Service Center 

P.O. Box 1331 

445 Hoes Lane 

Piscataway, NJ 08854-1331 
(201) 981-0060 


The document X3/SD-4 provides a list of all active X3 and related ISO projects, 
including approved standards. X3/SD-4 is available from: 


CBEMA 

X3 Secretariat 

311 First Street, NW Suite 500 
Washington, DC 20001-2178 
(202) 737-8888 


ANSI and ISO standards can be ordered from: 


Sales Department 

American National Standards Institute 
1430 Broadway 

New York, NY 10018 

(212) 642-4900 
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A.2 Standards Closely Related to the 1003.1 Document. 


A.2.1 System Interface. The 1003.1 Working Group will be continuing 
work in the area of system interface functions, preparing a supplement to IEEE 
Std 1003.1-1988. Tasks this group will be addressing include: 

(1) Language-independent service specifications. 
(2) An enhanced and unified data interchange format. 
(3) Various additional functions suggested as a result of this standard. 

Contact the IEEE Standards Office to participate in this effort. If you are 
interested in participating in this effort, or receiving working drafts and group 
mailings, contact the IEEE Standards Office; the address is listed in the Fore- 
word. 


A.2.2 C Language Standard. This document refers to the C Language 
Standard effort presently under development by Technical Committee X3J11 of 
the Accredited Standards Committee X3—Information Processing Systems. The 
X3J11 and 1003.1 groups have been cooperating to ensure that the standards 
are complementary and not overlapping. At the time of publication, the most 
recent X3J11 material was the version for public comment of the ANSI/X3.159- 
198x Programming Language C' Standard, available from: 


Global Engineering Documents, Inc. 
2805 McGaw Street 

Irvine, CA 92714 

(800) 854-7179 

(714) 261-1455 

Telex: 692 373 


Once the X3J11 document is approved, it will be available from the ANSI 
address given previously. 


A.2.3 Shell and Utilities. This area is currently in development by IEEE 
Computer Society Working Group 1003.2. The proposed 1003.2 standard 
defines a source code level interface to shell services and common utility pro- 
grams for application programs conforming to IEEE Std 1003.1-1988.* The pro- 
posed standard is being designed to be used by both application programmers 
and system implementors. 

The following goals have been established for the Working Group: 

Specify a standard interface that may be accessed in common by both applica- 
tions programs and user terminal-controlling programs to provide services of a 
more complex nature than the primitives provided by IEEE Std 1003.1-1988. 
This interface shall be implementable on conforming IEEE Std 1003.1-1988 


* An IEEE Std 1003.1-1988 conforming implementation is not necessarily required to support these 
application programs. Implementations could be produced that are conformant only to those 
1003.1 features required by the proposed 1003.2 standard, and that cannot claim full 
conformance to all of IEEE Std 1003.1-1988. 
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systems. It shall include the following components: 
(1) Application program primitives to specify instructions to an 
implementation-defined “shell” facility. 
(2) A standard command language for a shell that includes program execu- 
tion, I/O redirection and pipelining, argument handling, variable substitu- 
tion and expansion, and a series of control constructs similar to other high- 
level structured programming languages. 
(3) A recommended command syntax for command naming and argument 
specification. 
(4) Primitives to assist applications programs and the shell language in pars- 
ing and interpreting command arguments. 
(5) Recommended environment variables for use by shell scripts and applica- 
tion programs. 
(6) A minimum directory hierarchy required for the shell and applications. 
(7) A group of utilities that may be called from application programs for com- 
plex data manipulation and other tasks common to many applications. 
(8) An optional group of utilities to be used for the software development of 
applications. The Working Group is examining both C language and FOR- 
TRAN software development requirements. 
(9) Utilities and standards for the installation of applications. 

The following areas are outside the scope of this standard: 

(1) Operating system administrative commands (privileged processes, system 
processes, daemons, etc.). 

(2) Commands required for the installation, configuration, or maintenance of 
operating systems or file systems.* 

(3) Networking commands. 

(4) Terminal control or user-interface programs (visual shells, window 
managers, command history mechanisms, etc.). 

(5) Graphics programs or interfaces. 

(6) Text formatting programs or languages. 

(7) Database programs or interfaces (for example, SQL, etc.). 

The Working Group is considering an expansion of its scope to include a “User 
Portability Extension,” comprised of utilities which are used primarily by online 
users, such as full-screen editors. This subject area may be issued as a supple- 
ment to the first edition of the standard. 

At the time of this printing, no approved document existed. Working drafts 
were being circulated, with a target schedule of mid-1989 for balloting. 

Contact the IEEE Standards Office to participate in this effort. 


This is contrasted against paragraph 9, above, by its orientation to installing the operating 
system itself, versus application programs. The exclusion of operating system installation 
facilities should not be interpreted to mean that the non-privileged application installation 
procedures cannot be used for installing operating system components. 


A.2 Standards Closely Related to the 1003.1 Document. 165 


IEEE 
Std 1003.1-1988 IEEE STANDARD PORTABLE OPERATING SYSTEM 


A.2.4 Verification Testing. This area is currently in development by IEEE 
Computer Society Working Group 1003.3. A working draft is nearing comple- 
tion for test methods related to IEEE Std 1003.1-1988; further standards that 
relate to the other working groups in 1003 are under study. 

Contact the IEEE Standards Office to participate in this effort. 


A.2.5 Realtime Extensions. This area is currently in development by 
IEEE Computer Society Working Group 1003.4, with a charter to develop and 
ballot extensions to IEEE Std 1003.1-1988 to address service interfaces needed 
for portable realtime applications. 

The scope of the project includes the following realtime topics: 

(1) High Resolution Timers 

(2) Priority Scheduling 

(3) Semaphores 

(4) Contiguous Files 

(5) Inter-Process Message Passing 
(6) Event Notification 

(7) Memory Locking 

(8) Asynchronous I/O 

(9) Synchronous I/O 

The Working Group is an outgrowth of the /usr/group Technical Conmiines 
Realtime Subcommittee, with whom it holds joint meetings. At the time of this 
printing, no published document existed. Working drafts were being circulated. 

Contact the IEEE Standards Office to participate in this effort. 


A.2.6 Ada Language Bindings. This area is currently in development by 
IEEE Computer Society Working Group 1003.5, with a charter to develop and 
ballot extensions to IEEE Std 1003.1-1988 to provide an Ada language binding 
specification to the appropriate operating system interfaces. 

Contact the IEEE Standards Office to participate in this effort. 


A.2.7 Trusted System Extensions. This area is currently in development 
by IEEE Computer Society Working Group 1003.6, with a charter to develop and 
ballot extensions to IEEE Std 1003.1-1988 to address service interfaces needed 
for trusted, or high security systems. The Working Group is an outgrowth of 
the /usr/group Technical Committee Security Subcommittee, with whom it holds 
joint meetings. 

Contact the IEEE Standards Office to participate in this effort. See also 
Trusted Systems §A.4.2. 


A.2.8 Open System Guidelines. This area is currently in development by 
IEEE Computer Society Working Group 1003.0. 
Contact the IEEE Standards Office to participate in this effort. 


A.2.9 System Administration Extensions. A new working group is being 
formed in IEEE to cover POSIX system administration issues. 
Contact the IEEE Standards Office to participate in this effort. 
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A.2.10 Networking Standards. A new working group is being formed in 
IEEE to cover POSIX networking-related issues. Contact the IEEE Standards 
Office to participate in this effort. 

The ISO/OSI (Open System Interconnect) networking specifications are avail- 
able from CBEMA or ANSI (and 802.n from the IEEE Standards Office): 


OSI Model ISO 7498 (ANSI 
Layer 1 CSMA/CD IEEE 802.3 (IEEE) 
Token Bus IEEE 802.4 (IEEE) 
Token Ring IEEE 802.5 (IEEE) 
Layer 2 Link Layer Control IEEE 802.2 (IEEE) 
CCITT DR X.212 (CBEMA) 
Layer 3 Network Layer ISO 8348, 8473, 7777 (CBEMA) 
Layer 4 Transport Layer ISO 8072, 8073 (CBEMA) 
Layer 5 Session Layer ISO 8326, 8327 (CBEMA) 
Layer 6 Presentation Layer ISO DP 8822, DP 8823 (CBEMA) 
Layer 7 Applications Layer 
CASE (Common Services) ISO DP 8649, DP 8650 (CBEMA) 
FTAM (File Transfer) ISO DP 8571 (CBEMA) 
Mail/Message CCITT X.400 series (CBEMA) 
Job Transfer ISO DP 8831, DP 8832 (CBEMA) 
Wide Area Net Layers 1-3 CCITT X.25 (CBEMA) 


A.2.11 Language Standards. The following language standards are avail- 
able from ANSI: 


Ada Mil Std 1815-A-1983 
Basic X3.113-1987 
COBOL X3.23-1985 
FORTRAN X3.9-1978 

Mumps MDC X11.1-1984 
Pascal X3.97-1983 


A.2.12 Graphics Standards. The following graphics-related standards are 
available from CBEMA or ANSI: 


GKS X3.124-1985 Graphical Kernel System; C language bindings are 
in progress (0533-D). (ANSI) 

PHIGS X3.144-198x Programmers’ Hierarchical Interactive Graphics 
System; C language bindings are in progress (0534-D). 
(CBEMA) 

CGM X3.122-1986 Computer Graphics Metafile, formerly known as 


VDM, Virtual Device Metafile. (CBEMA) 
X3H3.6 This working group is addressing windowing standards and 
display management for graphical devices. (CBEMA) 
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A.2.138 Database Standards. The following database standards are avail- 
able from ANSI: 
NDL X3.133-1986 Database Language NDL. (Network Databases.) 
SQL X3.135-1986 Database Language SQL. (Relational Databases.) 


A.3 Industry Open Systems Publications. The following publications 
describe recommendations formed by industry groups (as opposed to a single 
company) about related standards efforts. 

The X/OPEN Portability Guide III (multiple volumes): 


Prentice-Hall 
200 Old Tappan Road 
Tappan, NJ 07675 


Reports of the /usr/group Technical Committees: 


/usr/group 
4655 Old Ironsides Drive #200 
Santa Clara, CA 95054 


Applications Environment Specifications published by the Open Software 
Foundation: 


Open Software Foundation 
20 Ballard Way 
Lawrence, MA 01843 


A.4 US Government Standards. 


A.4.1 Federal Information Processing Standards (FIPS). Standards 
designated by the US Government as Federal Information Processing Standards 
frequently refer back to standards listed above. 

For copies of POSIX-related FIPS documents and the NBS PCTS (POSIX FIPS 
Conformance Test Suite), contact: 


National Technical Information Service 
US Department of Commerce 

5285 Port Royal Road 

Springfield, VA 22161 

(703) 487-4650 


The Interim FIPS on POSIX announced in April of 1988 is based on Draft 12 of 
this document, which means that it differs in a few significant ways from this 
final standard. NBS has announced its intention that these differences will be 
eliminated in the next version of the FIPS, expected in late 1988. 


A.4.2 Trusted Systems. A standard for secure, or trusted, systems, the 
Depariment of Defense Trusted Computer System Evaluation Criteria, Depart- 
ment of Defense Standard DoD 5200.28-STD, December 19835, is available from: 
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Office of Standards and Products 

National Computer Security Center 

Fort Meade, MD 20755-6000 

Attn: Chief, Computer Security Standards 
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B. Rationale and Notes 


This appendix summarizes the deliberations of the IEEE 1003.1 Working 
Group, the committee charged by IEEE with devising an interface standard for a 
portable operating system interface for computer environments, IEEE Std 
1003.1-1988. 

This appendix is derived in part from copyrighted draft documents developed 
under the sponsorship of /usr/group*, as part of an ongoing program of that 
association to support the IEEE 1003 standards program efforts. 

The appendix is being published along with the standard to assist in the pro- 
cess of review. It contains historical information concerning the contents of the 
standard and why features were included or discarded by the Working Group. 
It also contains notes of interest to application programmers on recommended 
programming practices, emphasizing the consequences of some aspects of the 
standard that may not be immediately apparent. 


B.1 Introduction. The IEEE Std 1003.1-1988 is based on the UNIX operating 
system developed by AT&T Bell Laboratories, and derives from efforts of the 
Standards Committee of /usr/group, an association of individuals, corporations, 
and institutions with an interest in the UNIX system that has long worked 
toward the development of independent industry-driven standards. The IEEE 
1003 Working Group represents a cross-section of the UNIX system community: 
it consists of over 450 members representing hardware manufacturers, vendors 
of operating systems and other software development tools, software designers, 
consultants, academics, authors, applications programmers, and others. In the 
course of its deliberations, it has reviewed related American and international 
standards, both published and in progress. 

Conceptually, this standard describes a set of fundamental services the 1003 
Working Group feels are needed for the efficient construction of application pro- 
grams. Access to these services has been provided by defining an interface, 
using the C programming language, which establishes standard semantics and 


* Copyright © 1987 by /usr/group. Reprint rights granted to the IEEE for this appendix. 


/usr/group is a registered trademark of /usr/group, the International Network of UNIX System 
Users. 
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syntax. Since this interface enables application writers to write portable 
applications—it was developed with that goal in mind—it has been dubbed 
POSIX, an acronym for Portable Operating System Interface. The name POSIX, 
suggested by Richard Stallman, was adopted during the printing of the Trial 
Use Standard. 

Although originally coined by the IEEE to refer to IEEE Std 1003.1-1988, the 
term POSIX more correctly refers to a family of related standards or working 
groups, 1003.n. These other activities are described in Appendix A. There are 
some cases where this Rationale (and the standard itself) uses the term POSIX 
as a synonym for IEEE Std 1003.1-1988. This incorrect usage is maintained for 
purposes of readability only. 

As explained in the Foreword, the term POSIX is expected to be pronounced 
pahz-icks, as in positive, not poh-six, or other variations. The 1003 Working 
Group has published the pronunciation of its term in an attempt to promulgate 
a standardized way of referring to a standard operating system interface. 

The intended audience for this standard is all persons concerned with an 
industry-wide standard operating system based on the UNIX system. This 
includes at least four groups of people: 

(1) persons buying hardware and software systems; 

(2) persons managing companies that are deciding on future corporate com- 
puting directions; 

(3) persons implementing operating systems, and especially; 

(4) persons developing applications where portability is an objective. 


B.1.1 Scope. This Rationale focuses primarily on additions, clarifications, 
and changes made to the UNIX system as described in the Base Documents 
§B.1.3 from which the standard was derived. It is not a rationale for the UNIX 
system as a whole, since the Working Group was charged with codifying existing 
practice, not designing a new operating system. No attempt is made in this 
Rationale to defend the pre-existing structure of UNIX systems. It is primarily 
deviations from existing practice, as codified in the Base Documents, that are 
explained or justified here. 

Material which is “outside the scope” or otherwised not addressed by this 
standard is implicitly “implementation-defined” if it is included in an implemen- 
tation. 

The Rationale discusses some UNIX system features that were not adopted 
into the standard. Many of these are features that are popular in some UNIX 
system implementations, so that a user of those implementations might ques- 
tion why they do not appear in the standard. It is hoped that this Rationale can 
provide appropriate answers. 

There are choices allowed by the standard for some details of the interface 
specification; some of these are specifiable optional subsets of the standard. See 
Symbolic Constants §B.2.10. See also Specific Derivations §B.1.3.3. 

After deliberation, the 1003.1 Working Group decided that although the ser- 
vices this standard provides have been defined in the C language, the concept of 
providing fundamental, standardized services should not be restricted only to 
programs of a particular programming language. The possibility of 
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implementing interfaces in alternate programming languages prompted the 
Working Group to coin the term IEEE Std 1003.1-1988 with the C Language 
Binding. The word Binding refers to the binding of a conceptual set of services 
and a standardized C interface which establishes rules and syntax for accessing 
them. Forthcoming extensions to this standard are expected to include bindings 
for other programming languages. 

The current version of the C Standard will be the basis for functional defini- 
tions of core services that are independent of programming languages. The 
standard as it stands now can be thought of as a C Language Binding. Chapters 
1 through 7, and 9, correspond roughly to the C language implementation of 
what will be defined in the programming language-independent core services 
section of the standard; Chapter 8 corresponds to be the C language-specific sec- 
tion. 

Readers are warned that the criteria used to choose the programming 
language-independent core services may be different from expected. The core 
services represent services that are common to those programming languages 
likely to form language bindings to this standard—the greatest common denom- 
inator. They are not chosen to reflect the most important system services of an 
ideal operating system. For this reason, some fundamental system services are 
not included in this section. As an example, memory management routines 
would at first seem to be a core service—they are an absolutely fundamental 
system service. They must, however, be included in language-specific portions 
of the standard because programming languages such as FORTRAN have tradi- 
tionally not provided memory management. Categorizing memory management 
as a core service would impose unreasonable requirements for FORTRAN imple- 
mentations. 

Implementors and programmers can rest assured, however, that any pro- 
gramming language traditionally supporting memory management will include 
those routines in the language-dependent sections of their bindings. Work will 
be done at a later time to standardize the classes of functions that must be 
included in the language-dependent sections of language bindings if those func- 
tions have been traditionally implemented for that language. This will ensure 
that certain classes of critical functions, such as Memory management, will not 
be excluded from any applicable language binding; see Language-Dependent 
Services for the C Programming Language §B.2.2.3. 

The standard is not a tutorial on the use of the specified interface, nor is this 
Rationale. However, the Rationale includes some references to well-regarded 
historical books on the UNIX System in Historical Implementations §B.11.2. 


B.1.2 Purpose. Several principles guided the Working Group’s decisions. 
B.1.2.1 Application Oriented. The basic goal of the Working Group was 
to promote portability of application programs across UNIX system environ- 
ments by developing a clear, consistent, and unambiguous standard for the 
interface specification of a portable operating system based on the UNIX system 
documentation. This standard codifies the common, existing definition of the 
UNIX system. There was no attempt to define a new system interface. 
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B.1.2.2 Interface, Not Implementation. The standard defines an inter- 
face, not an implementation. No distinction is made between library functions 
and system calls: both are referred to as functions. No details of the implemen- 
tation of any function are given (although historical practice is sometimes indi- 
cated in the Rationale). Symbolic names are given for constants (such as signals 
and error numbers) rather than numbers. 

B.1.2.3 Source, Not Object, Portability. The standard has been writ- 
ten so that a program written and translated for execution on one conforming 
implementation may also be translated for execution on another conforming 
implementation. The standard does not guarantee that executable (object or 
binary) code will execute under a different conforming implementation than 
that for which it was translated, even if the underlying hardware is identical. 
The Working Group has, however, attempted to put few impediments in the way 
of binary compatibility, and some remarks are found in this Rationale. See 
Requirements §B.2.2.1.1 and Configurable System Variables §B.4.8. 

B.1.2.4 The C Language and X3J11. The standard is written in terms 
of the standard C language as specified in the C Standard (ANSI/X3.159-198x 
Programming Language C Standard) produced by the X3J11 Working Group. 
See Conformance §2.2. Guidelines used in negotiations between the two 
Working Groups are discussed below in POSIX and the C Standard §B.1.4. 

B.1.2.5 No Super-User, No System Administration. There was no 
intention to specify all aspects of an operating system. System administration 
facilities and functions are excluded from the standard, and functions usable 
only by the super-user have not been included. This Rationale notes several 
such instances. Still, an implementation of the standard interface may also 
implement features not in the standard: see Requirements §2.2.1.1. The stan- 
dard is also not concerned with hardware constraints or system maintenance. 

B.1.2.6 Minimal Interface, Minimally Defined. In keeping with the 
historical design principles of the UNIX system, the standard is as minimal as 
possible. For example, it usually specifies only one set of functions to implement 
a capability. Exceptions were made in some cases where long tradition and 
many existing applications included certain functions, such as creat() §5.3.2. In 
such cases, as throughout the standard, redundant definitions were avoided: 
creat() §5.3.2 is defined as a special case of open() §5.3.1. Redundant functions 
or implementations with less tradition were excluded. For example, seekdir() 
and telldir() were not included in Directory Operations §5.1.2. 

B.1.2.7 Broadly Implementable. The Working Group has endeavored 
to make all specified functions implementable across a wide range of existing 
and potential systems, including: 

(1) All of the current major systems that are ultimately derived from AT&T 
code (Version 7 or later). 

(2) Compatible systems that are not derived from AT&T code. 

(3) Emulations hosted on entirely different operating systems. 

(4) Networked systems. 

(5) Distributed systems. 

(6) Systems running on a broad range of hardware. 
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No direct references to this goal appear in the standard, but some results of it 
are mentioned in this Rationale. 

B.1.2.8 Minimal Changes to Historical Implementations. There are 
no known Historical Implementations §B.1.3.2 that will not have to change 
in some area to conform to the standard, and in a few areas the standard does 
not exactly match any existing system interface (for example, see 
O_NONBLOCK §B.6). Nonetheless, there is a set of functions, types, definitions, 
and concepts that form an interface that is common to most historical imple- 
mentations. The standard specifies that common interface and extends it in 
areas where there has historically been no consensus, preferably 

(1) by standardizing an interface like one in an historical implementation, 
e.g., Directories §5.1, or; 

(2) by specifying an interface that is readily implementable in terms of, and 
backwards compatible with, existing implementations, such as Extended 
tar Format §10.1.1, or 

(3) by specifying an interface that, when added to an historical implementa- 
tion, will not conflict with it, like O_NONBLOCK §B.6. 

Required changes to historical implementations have been kept as few as pos- 
sible, but they do exist, and this Rationale points out some of them. 

The standard is specifically not a codification of a particular vendor’s product. 
It is like the UNIX system, but it is not identical to it. The word UNIX is not 
used in the standard proper both for that reason, and because it is a trademark 
of a particular vendor. 

It should be noted that implementations will have different kinds of exten- 
sions. Some will reflect “historical usage” and will be preserved for execution of 
pre-existing applications. These functions should be “deprecated” and the stan- 
dard functions used for new applications. Some extensions will represent func- 
tions beyond the scope of POSIX. These need to be used with careful manage- 
ment to be able to adapt to future POSIX Extensions, and/or port to implementa- 
tions that provide these services in a different manner. 

B.1.2.9 Minimal Changes to Existing Application Code. The Work- 
ing Group wished to make less work for application developers, not more. How- 
ever, because every known historical implementation will have to change at 
least slightly to conform, some applications will have to change. This Rationale 
points out the major places where the standard implies such changes. 

B.1.2.10 TEEE Consensus Process... The IEEE consensus process was 
used in deliberations. There are several levels of participation: 

(1) Correspondents. Those interested in following the development of the 
standard could subscribe to a mailing list to which copies of drafts, working 
documents, and related material were sent. Also, anyone (including indivi- 
duals, companies, government agencies, or other organizations) could send 
comments (or RFCs, Proposals, or Notes) to the Working Group. 

(2) Working Group. This was the group responsible for producing the stan- 
dard document. It met four times a year and produced many drafts. It also 
produced the Trial Use and Full Use Standards, and was responsible for 
resolving balloting objections to them. The Working Group was composed of 
individuals, even though many of them worked for companies with interests 
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in the field. 

(3) Balloting Group. This group voted on the proposed standards in the 
manner detailed in the next subsection. The Balloting Group, like the Work- 
ing Group, was composed of individuals. Most of the people on the Working 
Group also were in the Balloting Group, although the latter included many 
others, as well. 

(4) Institutional Representatives. Exceptions to the individual composi- 
tion of the Balloting Group were the Institutional Representatives, who 
represented related standards bodies or professional organizations (in this 
case, USENIX, /usr/group, and X/Open). 

Decisions of the Working Group were not made by vote, not even of a large 
majority. Decisions were made by consensus, which required that every indivi- 
dual believe that: 

(1) their point of view had been heard. 

(2) their point of view had been understood. 

(3) other individuals’ points of view were adequately understood. 
(4) there was general consensus. 

A common way of moving discussion along was to ask if anyone would ballot 
“no” on a particular issue. 

B.1.2.11 IEEE Balloting Process. The IEEE balloting process was used 
to attain the ANSI requirement for a consensus acceptance of a document as a 
standard. 

Balloting in IEEE is done by individuals who are members of IEEE or affiliated 
with the IEEE Computer Society. They are given thirty days in which to return 
the ballots, and 75% of those in the balloting group must return ballots. 

Ballots from non-IEEE members (or non-Computer Society affiliates) are also 
included in the process, with comments and objections treated the same as those 
from members. However, non-IEEE members are not included in the percen- 
tages of returns required or the affirmative percentage required for approval. 
Possible ballot responses (excluding abstentions) are: 

(1) yes without comments. 

(2) yes with comments. The comments indicate areas that should be 
evaluated, but are not significant enough to warrant a negative ballot. 

(3) no with objections. A negative ballot must include specific objections 
and recommendations on how to resolve the objections. These objections 
indicate areas that must be fixed to resolve the negative ballot. 

At least 75% of those balloting (not abstaining) must provide an affirmative 
response. Each objection, and many of the comments, are translated into pro- 
posed changes; and any outstanding objections, along with the rationale for not 
making the changes to accommodate these objections, are fed back to the ballot- 
ing group. 

Members of the balloting group are given ten (or more) days to change: their 
ballots, with similar options as above; however, objections are limited to the pro- 
posed changes and/or failure to resolve key objections. It is possible for the 
number of negative responses to increase if a proposed change is objectionable, 
or if a significant objection has not been addressed. 
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In general, the balloting process moves fairly quickly towards a high degree of 
consensus. The final results are submitted to the IEEE Standards Board for 
approval, and include the balloting percentages as well as documentation of any 
unresolved negative objections. 

The Institutional Representatives were exceptions in several ways. 

(1) They are not required to be IEEE members. 

(2) They ballot for their Institutions, not as individuals. 

(3) Ballots of Institutional Representatives are reported separately to the 
IEEE Standards Board. 

As with other ballots, any unresolved negative objections are reported with 
the rationale for not incorporating the associated changes. However, the 
separate reporting of the Institutional ballots tends to make any objections more 
visible, particularly in that Institution’s areas of expertise; consequently, any 
unresolved objection could be enough to cause the document to be sent back to 
the balloting process for further resolution. 

The Trial Use period was from April 1986 to November 1987, when the ballot- 
ing of the revised document (Draft 12) began, and provided an additional level of 
industry consensus. The high visibility of the document, as well as its 
widespread distribution, provided additional feedback and information for the 
formulation of the current standard. See also Specific Derivations §B.1.3.3. 

B.1.2.12 WeirdNIX ... or destructive QA of a standard. 

As part of the evaluation of the Trial Use Standard, the IEEE 1003 Working 
Group offered prizes for the best new and technically legal interpretation of the 
POSIX standard which nevertheless violates the intuitive intent of the POSIX 
standard. 

The intent was to find how the standard might be misinterpreted, and then to 
correct the errors that the misinterpretations point out. Like destructive test- 
ing of hardware, you stress it until it breaks and then fix what broke so you can 
then stress it further. 

The criteria for judging the misinterpretations were: 

(1) It had to be an interpretation of the P1003.1 POSIX Trial Use standard (as 
published by IEEE) which conforms completely to the standard. For the pur- 
poses of the contest, Appendices C.5, E.1 and J were included as part of the 
standard, but no other Appendices. 

(2) It had to be represented as a detailed description in either pseudo-code 
and/or text as how an implementation could behave so as to conform with the 
standard and still do “the wrong thing.” Annotation as to why the interpre- 
tation is considered legal by the submitter was of significant value in judg- 
ing. 

(3) Interpretations had to be of topics discussed in the standard. Areas that 
are not covered by the standard are not eligible. Interpretations which use 
some features of the standard and then take advantage of something upon 
which the standard is silent (and thus should not be) were of significant 
value. 

The winners were judged by a subset of the IEEE 1003 Working Group. 

Prizes were awarded to the Best and Most Demented interpretations. Best is 
an interpretation that is legal and which is “likely,” in that one could reasonably 
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make the mistake and implement a system which did that. Most Demented is a 
legal interpretation that would not actually be implemented because it violates 
common sense. 
The prizes were: 
(1) HP 16C calculators, donated by Hewlett-Packard, 
(2) Having the winners’ names in a place of honor in the IEEE Std 1003.1- 
1988 final use standard, 
(3) A copy of the final use standard. 
The winners were announced at the USENIX conference in January 1987 and 
are recognized in the Foreword of this standard. 


WeirdNIX Post Mortem: The results of the contest indicated that the idea 
was probably sound, but the lack of available copies of the standard and the 
short contest period (dictated by meeting schedules) made it less successful than 
it could have been. Other standards, particularly in the computer area, might 
wish to consider trying this again with better planning. 


B.1.38 Base Documents. The Working Group consulted a number of docu- 
ments as representing features appropriate for consideration for inclusion in the 
standard. Full bibliographic information may be found in Bibliographic 
Notes §B.11. 

B.1.3.1 Related Standards and Documents. 
(1) 1984 /usr/group Standard 
(2) ANSI /X3.159-198x Programming Language C Standard 
(3) X/OPEN Portability Guide 

The most direct ancestor is the 1984 /usr/group Standard, which is con- 
sidered to be Draft 1 of the present standard. It, in turn, was largely derived 
from the programming interface of System III. The 1984 /usr/group Standard 
is also the principal ancestor of the Library section of the C Standard. 

The X3J11 and 1003.1 Working Groups cooperated closely. Details of the 
relations of the two standards they produced are listed in this Rationale in 
POSIX and the C Standard §B.1.4 because the C Standard is the standard 
most closely related to POSIX. POSIX is written in terms of the C Standard, 
although it is possible to have POSIX without Standard C: see Conformance 
SE2-2e 

The X/OPEN Portability Guide proved useful because X/Open had in many 
cases already addressed the same issues as P1003.1, though often in a slightly 
different context. 

The Working Group was aware of the Japanese SIGMA Project, which includes 
as a goal a common operating system interface specification, and there was a 
representative of SIGMA at many 1003.1 Working Group meetings. 

B.1.3.2 Historical Implementations. These include (with colloquial 
names in parentheses): 
(1) UNIX Time-Sharing System: UNIX Programmer’s Manual, Seventh Edi- 
tion (Version 7) 
(2) UNIX System III Programmer’s Manual 
(3) AT&T System V Interface Definition (SVID), Issue 2, Volumes 1-3 
(4) 4.3 Berkeley Software Distribution, Virtual VAX-11 Version (4.3BSD) 


178 Appendix B 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


Manuals 

The UNIX system has changed more since the 1984 /usr/group Standard was 
written than has the C language, and there are more variants of the former. 
Because of this, the present standard was radically reorganized and reformatted 
after the first draft and had many changes in content. Thus there is no single 
Base Document to provide context for all discussions in this Rationale, which 
instead discusses aspects of Version 7, System III, System V, and 4.3BSD that 
were included in this standard or that were considered in choosing what was 
included. 

Occasional mentions are made of the Eighth and Ninth Editions, which are 
successors of Version 7, the Bell Laboratories research system. The context is 
usually related to the streams inter-process communication mechanism, which 
is not in this standard but which has influenced discussions about inter-process 
communication mechanisms. 

Although 4.2BSD was the current Berkeley Software Distribution when most 
of the work on the standard was done, this Rationale refers to 4.3BSD instead 
(in most places) because the differences between the two versions are almost 
entirely in performance, the few programming interface differences are mostly 
outside the scope of this standard, and the 4.3BSD manuals actually describe 
4.2BSD better than the 4.2BSD manuals do. 

The System V manuals are never referenced because the SVID is more defini- 
tive. 

Much of the standard is closer to the SVID than to any other document. 

Parts of documentation of many other related systems were considered in 
deliberations on various aspects of the standard. As those were too numerous to 
list all of them, none of them will be mentioned by name. 

B.1.3.3 Specific Derivations. Some areas of the standard are clearly 
derived from facilities of specific systems. Most of the major areas are listed 
here, together with references to the sections of the standard where they occur. 
For most of them, there is also more detail in the corresponding sections of the 
Rationale. 

FIFOs The FIFO special file §2.3 facility exists in System III, the 
1984 /usr/group Standard, and System V, but not in Version 7, 
4.2BSD, or 4.3BSD. 

reliable signals 
Signals §3.3 includes reliable signals related to the 4.3BSD 
model. These were introduced to address concerns with signal 
reliability that were raised in balloting the Trial Use Standard 
(thus the name “reliable signals”). 

job control The job control §B.3.3 facility is derived from 4.3BSD and was 
introduced between the Trial Use and Full Use Standards. 

saved set-user-ID (saved set-group-ID) 

This optional capability, mostly in exec §3.1.2 and Set User 
and Group IDs §4.2.2, is derived from System V, and was 
introduced in the Trial Use Standard. 

supplementary groups 
A single group per process as in System V is the default, but 
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User Identification §4.2 (particularly getgroups() §4.2.3) 
allows multiple groups per process as in 4.3BSD as an option. 
This was introduced shortly before the Trial Use Standard. 

uname() The uname() §4.4.1 function is derived from the 1984 
/usr/group Standard, which took it from System III, and it is 
still in System V. It does not exist in Version 7 or 4.3BSD. 

opendir(), readdir(), rewinddir(), closedir() 
The section on Directory Operations §5.1 is derived from 
4.2BSD and was introduced in an early draft of the standard. It 
was later adopted in System V Release 3. 

mkdir(), rmdir(), rename() 
The three functions mékdir() §5.4.1, rmdir() §5.5.2, and 
rename() §5.5.3 are derived from 4.2BSD. Except for rename(), 
these functions now also appear in System V Release 3. 

termios Device- and Class-Specific Functions §7, while closer to 
System V than to 4.3BSD, does not correspond to any existing 
system because none was found adequate when considerations 
such as international character sets, fast interfaces, and net- 
works were taken into account. The final interface specification 
was introduced shortly before the Full Use Standard. 

archive format 
The Extended tar Format §10.1.1 is derived from the tar 
programs used in Version 7 and 4.3BSD, and provided with 
System V. The precise format in the Full Use Standard has 
evolved incrementally from that in earlier drafts of POSIX. The 
Extended cpio Format §10.1.2 is derived from that of 
System V. 

B.1.3.4 Working Documents. The model for the present Rationale was 
the Rationale prepared by the X3J11 Working Group to accompany the 
C Standard: X3J11/86-152, October 1, 1986 “Rationale for Draft Proposed 
American National Standard for Information Systems—Programming Language 
C.” Its influence may be seen most clearly in POSIX and the C Standard 
§B.1.4, but it also is present in more subtle ways throughout. 

References to programs, functions, or facilities of systems described by the 
Base Documents (such as the System V cpio utility program) have been freely 
included in this Rationale where relevant, even though they would be inap- 
propriate in the standard itself. References to programs, functions, or facilities 
not described by the base documents or to companies not directly associated 
with them have been excluded where possible. Exceptions have been made 
where facilities were derived from systems not described by the base documents, 
and where the word “may” is used to describe an option that permits behavior of 
such a system. 


B.1.4 POSIX and the C Standard. Some C language functions and defini- 
tions were handled by POSIX, but most by X3J11’s ANSI C Standard. The most 
general guideline was that POSIX retained responsibility for operating-system 
specific functions, while X3J11 defined C library functions. See also C 


180 Appendix B 


IEEE 
INTERFACE FOR COMPUTER ENVIRONMENTS Std 1003.1-1988 


Language Definitions §B.2.8 and Language-Specific Services for the C 
Programming Language §B.8. 

There are several areas in which the two standards differ philosophically: 

(1) Function parameter type lists. These appear in the C Standard and 
specify the types of the arguments and return values of functions in external 
references to them. POSIX does not include them, except in a few places to 
indicate variable number of arguments, e.g., File Control §B.6.5.2. Func- 
tion parameter type lists were not used because the Working Group was 
aware that some vendors would wish to implement POSIX in terms of a bind- 
ing to an historical variant of the C language instead of to the C Standard, 
since compilers for the latter would initially not be widespread. Since the 
C Standard does not require the use of function parameter type lists, the 
function definitions used in POSIX are nonetheless specified in terms of 
Standard C. See also Signals §B.3.3. 

(2) Single vs. multiple processes. The C Standard specifies a language 
that can be used on single-process operating systems and as a freestanding 
base for the implementation of operating systems or other standalone pro- 
grams. But the POSIX interface is that of a multi-process timesharing sys- 
tem. Thus POSIX has to take multiple processes into account in places where 
the C Standard does not mention processes at all, such as Rill() §3.3.2. See 
also Requirements §B.2.2.1.1. 

(3) Single vs. multiple operating system environments. The 
C Standard specifies a language that may be useful on more than one operat- 
ing system, and thus has means of tailoring itself to the particular current 
environment. POSIX is an operating system interface specification, and thus 
by definition is only concerned with one operating system environment, even 
though it has been carefully written to be Broadly Implementable §B.1.2.7 
in terms of various underlying operating systems. See also Requirements 
§B.2:2.1.4. 

(4) Translation vs. execution environment. POSIX is primarily con- 
cerned with the Standard C execution environment, leaving the translation 
environment to the C Standard. See also Requirements §B.2.2.1.1. 

(5) Hosted vs. freestanding implementations. A!] POSIX implementa- 
tions are hosted in the sense of the C Standard. See also the remarks on con- 
formance in the Foreword. 

(6) Text vs. binary file modes. X3J11-defines text and binary modes for a 
file. But the POSIX interface and historical implementations related to it 
make no such distinction, and all functions defined by POSIX treat files as if 
these modes are identical. (It is important not to say that POSIX files are 
either text or binary.) X3J11 wrote their definitions so that this interpreta- 
tion is possible. In particular, text mode files are not required to end with a 
line separator, which also means that they are not required to include a line 
separator at all. 

And there is a basic difference in approach between the X3J11 Rationale and 
the POSIX Rationale. The X3J11 Rationale addresses almost all changes as 
differences from the Base Documents of the C Standard, usually either Ker- 
nighan and Ritchie (see Related Standards §B.11.1) or the 1984 /usr/group 
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Standard. The present Rationale cannot do that, since there are many more 
variants of (and Base Documents for) the operating system interface than for 
the C language. The most noticeable aspect of this difference is that X3J11 
marks QUIET CHANGES from the Base Documents in its Rationale. The POSIX 
Rationale cannot include such markings, since a quiet change from one histori- 
cal implementation may correspond exactly to another historical implementa- 
tion, and may be very noticeable to an application written for yet another. 

B.1.4.1 Solely by POSIX. These return parameters from the operating 
system environment: cuserid() §4.2.4, ctermid() §4.7.1, ttyname() §4.7.2, and 
isatty() §4.7.2. 

The functions fileno() §8.2.1 and fdopen() §8.2.2 map between C language 
stream pointers and POSIX file descriptors. 

B.1.4.2 Solely by X3J11. There are many functions that are useful with 
the operating system interface and are required for conformance with the 
present standard, but that are properly part of the C Language. These are 
listed in Referenced C Language Routines §8.1, which also notes which 
functions are defined by both POSIX and X3J11. Certain terms defined by 
X3J11 are incorporated by POSIX in C Language Definitions §2.8. 

Some routines were considered too specialized by the 1003.1 Working Group 
to be included in the standard. These include bsearch() and qsort(). 

B.1.4.3 By Neither POSIX Nor X3J11. Some functions were considered 
of marginal utility and problematical when international character sets were 
considered: _towpper(), _tolower(), toascii(), and isascii(). 

Though malloc() §8.1 and free() §8.1 are in the C Standard and are required 
by Referenced C Language Routines §8.1 of the present standard, neither 
brk() nor sbrk() occur in either standard (although they were in the 1984 
/usr/group Standard), because this standard is designed to provide the basic 
set of functions required to write a Conforming POSIX Application; the underly- 
ing implementation of malloc() or free() is not an appropriate concern for the 
standard. 

B.1.4.4 Base by POSIX, Additions by X3J11. Since the C Standard does 
not depend on POSIX in any way, there are no items in this category. 

B.1.4.5 Base by X3J11,Additions by POSIX. X3J11 has to define errno 
if only because examining that variable is the only way to tell when some 
mathematics routines fail. But POSIX uses it more extensively, and adds some 
semantics to itin Error Numbers §2.5, which also defines some values for it. 

Many numerical limits used by X3J11 were incorporated by POSIX in Numer- 
ical Limits §2.9, and some new ones are added, all to be found in the header 
<limits.h>. 

The POSIX definition of signal §2.3 further specifies the C definition, and the 
entire mechanism of Signals §3.3 is much more elaborate. 

The function time() §4.5.1 is used by X38J11, but POSIX further specifies the 
time value. 

The function getenv() §4.6.1 is referenced in Environment Description §2.7 
and exec §3.1.2 and is also defined by X3J11. 

The function rename() §5.5.3 is extended to further specify its behavior when 
the new filename already exists or either argument refers to a directory. 
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B.1.4.6 Related Functions by Both. The X3J11 definition of compli- 
ance and the POSIX definition of Conformance §2.2 are similar, although the 
latter notes certain potential hardware limitations. 

POSIX defined a portable filename character set in General Terms §2.3, that 
is like the X3J11 identifier character set. However, POSIX did not allow upper- 
and lowercase characters to be considered equivalent. See filename portabil- 
ity §2.4. 

The exit() function is defined only by X3J11, because it refers to closing 
streams, and that subject, as well as fclose() itself, is defined almost entirely by 
X3J11. But POSIX defined _exit() §3.2.2, which also adds semantics to exit(). 
This also allows POSIX to ignore the X3J11 atexit() function. 

POSIX defined Aill() §3.3.2, while X3J11 defined raise(), which is similar 
except that it does not have a process ID argument, since the language defined 
by X3J11 does not incorporate the idea of multiple processes. 

The new functions sigsetjmp() $8.3.1 and siglongjmp() §8.3.1 were added to 
provide similar functions to X3J11 setjmp() and longjmp() that additionally 
save and restore signal state. 


B.1.5 Organization. 

B.1.5.1 Organization of the Standard. See the Foreword. 

It was decided very early that the traditional organization by manual section, 
as used in the 1984 /usr/group Standard, would be confusing in an IEEE stan- 
dard. That organization assumed some background that was not relevant to the 
purpose of the standard. It also made an implementation-oriented distinction 
between system calls and library routines, which were in separate sections. 

Two sections, Scope §1 and Definitions and General Requirements §2, 
have been added because they are traditional in IEEE standards. A Foreword 
was added for the same reason, even though it is not part of the standard 
proper. 

Although appendices were used in the Trial Use Standard to contain propo- 
sals for examination by the Balloting Group and the general public, the Full Use 
Standard has no proposal appendices, because the text of the standard proper 
must be complete. The Appendices of the Full Use Standard discuss either 
related standards or the Full Use Standard itself. The Full Use Standard con- 
tains some new material that was not in the Trial Use Standard, mostly that 
which was added to meet balloting objections. The most obvious examples are 
the addition of reliable signal considerations to Signals §3.3 (including the 
addition of Non-Local Jumps §8.3.1) and the resolution of Device- and 
Class-Specific Functions §7. See also Specific Derivations $B.1.3.3. 

Because there were too many notes interpolated in the text of the Trial Use 
Standard (which were nonetheless not part of the standard), and because there 
were still not enough to explain why the Working Group had made many diffi- 
cult decisions, the Working Group decided to add a Rationale and Notes Appen- 
dix, modeled after the one the X3J11 Working Group was producing for the 
C Standard. Most of the notes formerly in the main body of the draft were 
moved to the Rationale appendix, although some were deleted and others were 
incorporated into the text of the standard proper. 
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B.1.5.2 Organization of this Appendix. Just as the standard proper 
excludes all examples, footnotes, references, and appendices, this Rationale is 
also not part of the standard. The POSIX interface is defined by the standard 
alone. If any part of this Rationale is not in accord with that definition, the 
IEEE Standards Office should be so informed. In the meantime, conflicts 
between this Rationale and the standard are always resolved in favor of the 
body of the standard. 

All sections of this appendix beginning with Definitions and General 
Requirements §B.2 follow the exact structure of the standard, and aspects of a 
given section of the standard are considered in the corresponding section of the 
Rationale. Where a given discussion touches on several areas, attempts have 
been made to include cross-references within the text. 

References to the standard are in the same format as references within the 
standard to parts of itself, for example: General Terms §2.3. References to 
this Rationale are given as references to Appendix B of the standard, that is, the 
section numbers always begin with “B.” as in General Terms §B.2.3. Where a 
reference both to part of the standard and to a related note in the Rationale 
would be appropriate only the latter is given, because all parts of the Rationale 
implicitly refer to the corresponding parts of the standard. 

B.1.5.3 Typographical Conventions. A summary of typographical con- 
ventions is shown in Table B-1. 


Table B-1. Typographical Conventions 


Reference Example 
Command Name cpio 
Data Types long 
Defined Terms file 
Environment Variables PATH 
Error Numbers [EINTR] 
Function Arguments argl 
Functions open() 
Global Externals errno 
Headers <sys/stat.h> 
Limits {OPEN_MAX} 
Macros S_ISDIR 
Section References Process Termination §3.2 
Symbolic Constants { POSIX_VDISABLE} or O NONBLOCK 


Defined terms are shown in three styles, depending on context: 
(1) The initial appearance of the term is in italics. In the section General 
Terms §2.3, every reference to a term is italicized, which highlights the 
interrelationships between the definitions. 
(2) Subsequent appearances of the term are in the Roman font. 
(3) Cross references to terms from outside section 2.3, such as seconds 
since the Epoch §2.3, are shown in bold, because that is the style for all 
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cross references to terms and headings. 

Cross references to other section headings are not always exactly accurate. In 
this Rationale, in particular, keywords and other short phrases are sometimes 
used, rather than the full section heading text. 

Macros are either uppercase, as shown, or lowercase, depending on their his- 
torical origins. 

Symbolic constants are shown in two styles: those within braces are intended 
to call the reader’s attention to values in <limits.h> and <unistd.h>; those 
without braces are normally defined by one or a few related functions. 

In this Rationale, occasional use is made of an historical artifact from the 
UNIX system shell. In the shell, the asterisk (*) is used in file names or other 
command line tokens to represent zero or more additional characters. Thus, the 
construct LC_* represents all the environment variables beginning with the 
characters LC_. 

Defined names that are normally in lowercase, particularly function names, 
are never used at the beginning of a sentence or anywhere else that normal 
English usage would require them to be capitalized. 

The above typographical conventions apply to both the standard and to this 
Rationale. There are also some conventions peculiar to the Rationale, regarding 
standards for the operating system interface and for the C language. These are 
used frequently in POSIX and the C Standard §B.1.4 and are shown in Table 
B-2. 


Table B-2. Short Name Usages 


Operating System ' 
Topic Tee ce C Programming Language 
Working Group 1003.1 X3J11 


standard IEEE Std 1003.1-1988 ANSI/X3.159-198x Programming 
Language C Standard 
short name POSIX C Standard 
Rationale Appendix B Rationale for American National 
Standard for Information Systems— 
Programming Language C 
short name __ this Rationale X3J11 Rationale 


The name POSIX is usually used for the IEEE Std 1003.1-1988 instead of the 
name 1003.1, because the latter is too easily confused with the name of the 
Working Group, 1003.1. 

“Standard C” or the “C Standard” will eventually come to mean “ISO C,” but 
currently refers to the ANSI /X3.159-198x Programming Language C Standard 
produced by the X3J11 Working Group. 
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B.1.5.4 Document Indexes. The document comes with two indexes that 
are produced by completely different methods: 

(1) The Identifier Index is built from hand-inserted macros in the document 
text. It points to the definition of each of the functions, headers, global vari- 
ables (such as errno), and families (groups of functions, such as the exec and 
wait families). 
(2) The Topical Index is primarily the product of AT&T’s Documenter’s Work- 
bench* software. A list of key symbols and phrases is stored in a file and a 
yacc-based program finds instances of these phrases in the document. 
Merged into the output of that process are all of the hand-inserted macros 
within the text, including definitions as well as the four categories of the 
Identifier Index. These merged macros cause the page number reference to 
be listed in bold face, such as: 


index entry ... 57, 22, 55-60, 105 


Thus, the bold reference is probably the most interesting first stop for the 
index user. Other references may or may not be of interest, but are included 
for completeness. The reader is warned that it may be difficult to find some 
indexed phrases on the pages shown; the phrase scanner occasionally makes 
intuitive leaps that connect unrelated words in a sentence; it is also possible 
that a phrase close to the bottom of a page may be referenced on the follow- 
ing page number. 

Of course, neither index is part of the standard and the presence or accuracy 
of terms and page references have no normative effect. Suggestions for correct- 
ing errors or improving the index are welcome; this same indexing software is 
used by all of the POSIX technical editors and many future standards may bene- 
fit. Address suggestions to the IEEE office listed in the Foreword, requesting 
that they be forwarded to the Technical Editor of the 1003 Working Group. 


B.2 Definitions and General Requirements. 


B.2.1 Terminology. The meanings specified in the standard for the words 
shall, should, and may are mandated by IEEE. 

In this Rationale, the words shall, should, and may are sometimes used to 
illustrate similar usages in the standard. However, the Rationale itself does not 
specify anything regarding implementations or applications; see Organization 
of this Appendix §B.1.5.2. 


implementation-defined. This definition is analogous to that of the 
C Standard, and, together with undefined and unspecified, provides a range of 
specification of freedom allowed to the interface implementor. 


* Documenter’s Workbench is a trademark of AT&T, Inc. 
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may. The use of may has been limited as much as possible, due both to confu- 
sion stemming from its ordinary English meaning, and to objections regarding 
the desirability of having as few options as possible and those as clearly speci- 
fied as possible. 


shall. Declarative sentences are sometimes used in the standard as if they 
included the word shall, and facilities thus specified are no less required. For 
example, the two statements: 

(1) The foo() function shall return zero. 

(2) The foo() function returns zero. 
are meant to be exactly equivalent. 


should. In this standard, the word should does not usually apply to the imple- 
mentation, but rather to the application. Thus the important words regarding 
implementations are shall, which indicates requirements, and may, which indi- 
cates options. 


supported. An example of this concept is the setpgid() function. If the imple- 
mentation does not support the optional job control feature, it nevertheless has 
to provide a function named setpgid(), even though its only ability is that of 
returning [ENOSYS]. 


undefined. See implementation-defined. 
unspecified. See implementation-defined. 


The definitions for unspecified and undefined appear nearly identical at first 
examination, but are not. Unspecified means that a conforming program may 
deal with the unspecified behavior, and it should not care what the outcome is. 
Undefined says that a conforming program should not do it because no defini- 
tion is provided for what it does (and implicitly it would care what the outcome 
was if it tried it). It is important to remember, however, that if the syntax per- 
mits the statement at all, it must have some outcome in a real implementation. 

Thus the terms undefined and unspecified apply to the way the application 
should think about the feature. In terms of the implementation it is always 
“defined:” there is always some result, even if it is an error. The implementa- 
tion is free to choose the behavior it prefers. 

This also implies that an implementation, or another standard, could specify 
or define the result in a useful fashion. The terms apply to the POSIX standard 
specifically. 

The term implementation-defined implies requirements for documentation 
that are not required for undefined (or unspecified). Where there is no need for 
a conforming program to know the definition, the term undefined is used, even 
though implementation-defined could also have been used in this context. In an 
ideal world, there could be a fourth term, specifying “We don’t say what this 
does; it’s acceptable to define it in an implementation, but you don’t need to 
document it,” and undefined would then be used very rarely for the few things 
for which any definition is not useful. 
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B.2.2 Conformance. These conformance definitions are descended from 
those of conforming implementation, conforming application, and conforming 
portable application, of the Trial Use Standard, but were changed to clarify 

(1) extensions, options, and limits; 
(2) relations among the three terms, and; 
(3) relations between POSIX and the C Standard. 
B.2.2.1 Implementation Conformance. These definitions allow appli- 
cation developers to know what they can depend on in an implementation. 

There is no definition of a strictly conforming implementation; that would be 
an implementation that provides only those facilities specified by the standard 
with no extensions whatsoever. This is because no actual operating system 
implementation can exist without system administration and initialization facil- 
ities that are beyond the scope of the present standard. 

B.2.2.1.1 Requirements. The word “support” is used rather than “pro- 
vide” in order to allow an implementation that has no resident software develop- 
ment facilities, but which supports the execution of a Strictly Conforming POSIX 
Application, to be a conforming implementation. See also Translation vs. 
Execution Environment §B.1.4. 

B.2.2.1.2 Documentation. The conforming documentation shall use 
the same numbering scheme as this standard for purposes of cross referencing. 
(This also eliminates the need for a definitive “laundry list.”) 

This proposal is consistent with and supplements the verification test suite 
developed by the 1003.3 Working Group. All options that an implementation 
chooses shall be reflected in <limits.h> and <unistd.h>. 

Hardware Failures: Many systems incorporate buffering facilities, main- 
taining updated data in volatile storage and transferring such updates to nonvo- 
latile storage asynchronously. Various exception conditions, such as a power 
failure or a system crash, can cause this data to be lost. The data may be associ- 
ated with a file that is still open, with one that has been closed, with a directory, 
or with any other internal system data structures associated with permanent 
storage. This data can be lost, in whole or part, so that only careful inspection 
of file contents could determine that an update did not occur. 

Also, interrelated file activities, where multiple files and/or directories are 
updated, or where space is allocated or released in the file system structures, 
can leave inconsistencies in the relationship between data in the various files 
and directories, or in the file system itself. Such inconsistencies can break 
applications that expect updates to occur in a specific sequence, so that updates 
in one place correspond with related updates in another place. 

For example, if a user creates a file, places information in the file, and then 
records this action in another file, a system or power failure at this point fol- 
lowed by restart may result in a state in which the record of the action is per- 
manently recorded, but the file created (or some of its information) has been 
lost. The consequences of this to the user may be arbitrarily bad. For a user on 
such a system, the only safe action may be to require the system administrator 
to have a policy that requires, after any system or power failure, that the entire 
file system must be restored from the most recent backup copy (causing all 
intervening work to be lost). 
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The characteristics of each implementation will vary in this respect, and may 
or may not meet the requirements of a given application or user. Enforcement 
of such requirements is beyond the scope of this standard. It is up to the pur- 
chaser to determine what facilities are provided in an implementation that 
affect the exposure to possible data or sequence loss, and also what underlying 
implementation techniques and/or facilities are provided that reduce or limit 
such loss, or its consequences. 

B.2.2.1.3 Conforming Implementation Options. Within this stan- 
dard there are some symbolic constants that, if defined, indicate that a certain 
option is enabled. Other symbolic constants exist in the standard for other rea- 
sons. This section was placed in the standard to help clarify which constants 
are related to true “options,” and which are related more to the behavior of 
differing systems. 

To accommodate historical implementations where there were distinct seman- 
tics in certain situations, but where one was not clearly better or worse than 
another, the standard at one point permitted either of (typically) two options 
using “may.” At the request of the 1003.3 Working Group, this was changed to 
be specified by formal options with flags. It quickly became obvious that these 
would be treated as options that could be selected by a purchaser, when the 
intent of the Working Group was to allow either behavior (or both, in some 
cases) to conform to the standard, and to constrain the application to accommo- 
date either. Thus, these options were removed and the phrase “An implementa- 
tion may either” introduced to replace the option. Where this phrase is used, it 
indicates that an application shall tolerate either behavior. 

The Working Group intends that all conforming applications shall tolerate 
either behavior, and that only in the most exceptional of circumstances (driven 
by technical need) should a purchaser specify only one behavior. Backwards 
compatibility is not considered exceptional enough, as this is not consistent with 
the intent of the standard: to promote the portability of applications (and the 
development of portable applications). 

An application can tolerate these behaviors either by ignoring the differences 
Gf they are irrelevant to the application) or by taking an action to assure a 
known state. It might be that that action would be redundant on some imple- 
mentations. 

Validation programs, which are applications in this sense, could either report 
the actual result found, or simply ignore the difference. In no case should either 
acceptable behavior be treated as an error. This may complicate the validation 
slightly, but is more consistent with the intent of this permissible variation in 
behavior. 

In certain circumstances, the behavior may vary for a given process. For 
example, in the presence of networked file systems, whether or not dot and dot- 
dot are present in the directory may vary with the directory being searched, and 
the program would only be portable if it tolerated, but did not require, the pres- 
ence of these entries in a directory. 

In situations like this, it is typically easier to simply ignore dot and dot-dot if 
they are found, than to try to determine if they should be expected or not. 
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B.2.2.2 Application Conformance. These definitions guide users or 
adaptors of applications in determining on which implementations an applica- 
tion will run and how much adaptation would be required to make it run on oth- 
ers. These three definitions are modeled after related ones in the C Standard. 

The standard (and this Rationale) occasionally use the expressions portable 
application or conforming application. As they are used, these are synonyms 
for any of these three terms. The differences between the three classes of appli- 
cation conformance relate to the requirements for other standards, or, in the 
case of the Conforming POSIX Application Using Extensions, to implementation 
extensions. When the two looser expressions are used, it should be apparent 
from the context of the discussion which of the more formal names is appropri- 
BuO: 

B.2.2.2.1 Strictly Conforming POSIX Application. This definition 
is analogous to that of a Standard C conforming program. 

The major difference between a Strictly Conforming POSIX Application and a 
Standard C strictly conforming program is that the latter is not allowed to use 
features of POSIX that are not in the C Standard. 

B.2.2.2.2 Conforming POSIX Application. Examples of <National 
Bodies> include ANSI, BSI, and AFNOR. 

B.2.2.2.3 Conforming POSIX Application Using Extensions. Due 
to possible requirements for configuration or implementation characteristics in 
excess of the specifications in <limits.h> §2.9 or related to the hardware (such 
as array size or file space), not every Conforming POSIX Application Using 
Extensions will run on every conforming implementation. 

B.2.2.3 Language-Dependent Services for the C Programming 
Language. This standard is, for historical reasons, both a specification of an 
operating system interface and a C binding for that specification. 

It is clear that these two need to be separated into separate entities, but the 
urgency of getting any standard out, and the fact that C is the de facto primary 
language on systems similar to the UNIX system, makes this a necessary and 
workable situation. 

Nevertheless, work will be done on language bindings, beyond that for C, 
before the specification and the current binding are separated. Language bind- 
ings for languages other than C should not model themselves too closely on the 
C binding, and in the process pick up various idiosyncrasies of C. 

Where functionality is duplicated in this standard (e.g. open() and creat()) 
there is no reason for that duplication to be carried forward into another 
language. On the other hand, some languages have functionality already in 
them that is essentially the same as that provided in this standard. In this 
case, a mapping between the functionality in that language and the underlying 
functionality in this standard is a better choice than mimicking the C binding. 

Since C has no syntax for I/O, and I/O is a large fraction of this standard, the 
paradigm of functions has been used. This may not be appropriate to another 
language. For example, FORTRAN’s REWIND statement is a candidate to map 
onto a special case of /seek(), and its SEEK statement may completely cover for 
lseek(). If this is the case, there is no reason to provide SUBROUTINEs with the 
same functionality. In the more general case, file descriptors and FORTRAN’s 
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logical unit numbers may have a useful mapping. FORTRAN’s ERR= option in 
V/O operations might replace returning —1; the whole concept of errors might be 
handled differently. 

As was done with C, it is not unreasonable for other language bindings to 
specify some areas that are undefined or unspecified by the underlying language 
standard, or which are permissible as extensions. This may, in fact, solve some 
difficult problems. 

Using as much as possible of the target language in the binding enhances por- 
tability. If a program wishes to use some POSIX capabilities, and these are 
bound to the language statements, rather than appearing as additional pro- 
cedure or function calls, and the program does in fact conform to the language 
standard while using those functions, it will port to a larger range of systems 
than one that is obligated to use procedure or function calls introduced specifi- 
cally for the binding to POSIX to do the same thing. 

A program which requires the POSIX capabilities which are not bound to the 
standard language directly (as above) has no chance to be portable outside the 
POSIX environment. It doesn’t matter whether the extension is syntactic or a 
new function; it still won’t port without effort. Given this, it seems unreason- 
able not to consider language extensions when determining how best to map the 
functionality of POSIX into a particular language binding. For example, a new 
statement similar to READ, which loads the values from a call like stat(), might 
be the best solution for reading the data lists returned as structures in C intoa 
list of FORTRAN variables. 

It should be clear that no attempt to mimic printf() or scanf() (or the rest of 
the Standard C functions) should be made, but rather that the equivalent func- 
tions in the language should be used. (Formatted READ and WRITE in FOR- 
TRAN, read/readin and write/writeln in Pascal, for example.) 

It should be noted that there is inherently a special relationship between an 
operating system standard and a language standard. It is unlikely that stan- 
dards for other kinds of features (such as graphics) will have much likelihood of 
binding directly to statements in a general purpose language. However, an 
operating system standard should be providing the services required by a 
language, and there should be a good chance of this happening. This is an 
unusual situation, and the natural tendency to use only new functions and pro- 
cedures when creating a binding should be examined carefully. (A one-to-one 
binding in all cases is probably too much to ask, but bindings such as those for 
standard I/O in Chapter 8 of this standard are quite reasonable.) 

Binding directly to the language, where possible, should be encouraged both 
by making maximal use of the mapping between the operating system and the 
language that naturally exists, and where appropriate, for the languages to 
request changes to the operating system to facilitate a better such mapping. (A 
future inclusion of a truncate function, specifically for the FORTRAN ENDFILE 
statement, but which is also generally useful, is a good example.) 

Clearly, part of the job of creating a binding is choosing names for functions 
which are introduced, and these will need to be appropriate for that language. 
It may be reasonable to use other than the most restrictive form of a name, 
since, as discussed previously, using these functions inherently makes the 
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application not portable to systems which are not POSIX, and if POSIX confor- 
mant systems typically accept names which the lowest common denominator 
system will not, there is no reason to a priori exclude such names. (The specific 
example is C, where it is typically “non-UNIX” systems that limit external iden- 
tifiers to six characters.) 

See Scope §B.1.1 for additional information about C bindings. 

B.2.2.3.1 Types of Conformance. 

B.2.2.3.2 C Standard Language-Dependent System Support. The 
issue of “namespace pollution” needs to be understood in this context. See 
POSIX Symbols §B.2.8.2. 

B.2.2.3.3 Common Usage C Language-Dependent System Sup- 
port. The issue of “namespace pollution” needs to be understood in this context. 
See POSIX Symbols §B.2.8.2. 

B.2.2.4 Other C Language Related Specifications. The information 
concerning the use of library functions was adapted from a description in the 
C Standard. Here is an example of how an application program can protect 
itself from library functions that may or may not be macros, rather than true 
functions: 

The atoi() function may be used in any of several ways: 
(1) by use of its associated header (possibly generating a macro expansion) 


Pinelude <—stdilabes he 
[= a eee 


i = aLloa(ster): 
(2) by use of its associated header (assuredly generating a true function call) 


#includer<stdllibeh= 
Pabguolee LUG 


EE SI 
1 = atoi(str); 
or 


finclude, <stalilb.in= 
ale ale 


1 = (avo) (ste): 
(3) by explicit declaration 


exLern int aboi Meonst char *) ; 
ee a tf 


d= aALOIStEr) ; 
(4) by implicit declaration 
oe ea | 


1a wonw( St 1): 


(Assuming no function prototype is in scope. This is not allowed by X3J11 
for functions with variable arguments; furthermore, parameter type conver- 
sion “widening” is subject to different rules in this case.) 
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Note that the C Standard reserves names starting with ’ ’ for the com- 
piler. Therefore, the compiler could, for example, implement an intrinsic, 
built-in function _asm_builtin_atoi(), which it recognized and expanded into 
inline assembly code. Then, in <stdlib.h>, there could be the following: 


pdetiie ator (xX) asm burltin eto1 (x) 


The user’s “normal” call to atoi() would then be expanded inline, but the 
implementor would also be required to provide a callable function named 
atoi() for use when the application requires it; for example, if its address is 
to be stored in a function pointer variable. 


B.2.3 General Terms. Many of these definitions are necessarily circular, 
and some of the terms (such as process ) are variants of basic computing science 
terms that are notoriously hard to define. Some are defined by context in the 
prose topic descriptions of General Concepts §2.4, but most appear in the 
alphabetical glossary format of General Terms §2.3. All technical terms not 
explicitly defined have definitions in the JEEE Dictionary. See Bibliographic 
Notes §B.11.1. 

Some definitions must allow extension to cover terms or facilities that are not 
explicitly mentioned in the standard. For example, the definition of file must 
permit interpretation to include streams, as found in the Eighth Edition. The 
use of abstract intermediate terms (such as object in place or in addition to file) 
has mostly been avoided in favor of careful definition of more traditional terms. 

Some terms in the following list of notes do not appear in the standard; these 
are marked prefixed with a asterisk (*). Many of them have been specifically 
excluded from the standard because they concern system administration, imple- 
mentation, or other issues that are not specific to the programming interface. 
Those are marked with a reason, such as “implementation-defined.” 


appropriate privileges. One of the fundamental security problems with UNIX 
systems has been that the privilege mechanism is monolithic—a user has either 
no privileges or all privileges. Thus, a successful “trojan horse” attack on a 
privileged process defeats all security provisions. Therefore, the standard 
allows more granular privilege mechanisms to be defined. For many existing 
implementations of the UNIX system, the presence of the term appropriate 
privileges in this standard may be understood as a synonym for super-user 
(UID 0). However, future systems will undoubtedly emerge where this is not the 
case and each discrete controllable action will have appropriate privileges asso- 
ciated with it. 


controlling terminal. The question of which of possibly several special files 
referring to the terminal is meant is not addressed in the standard. 


*cooperating implementation. This refers to a POSIX implementation that is 
done in combination with some other set of system specifications. This might be 
as simple as supporting a POSIX environment concurrently with some specific 
version of AT&Ts UNIX Operating System, or as complex as providing the POSIX 
environment with some different vendor’s products, such as MS/DOS from Micro- 
soft, VMS from Digital Equipment Company, etc. A cooperating environment 
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would fall somewhere on the gray scale from hosted implementations to native, 
depending on the degree of POSIX components that are serviced directly versus 
those that are converted to correspond with one of the other system’s implemen- 
tations. (Note that the POSIX facilities might be native, and the other system 
hosted; or both might be native.) 


*device number. The concept is handled in stat() §5.6.2 as ID of device. 


directory. The format of the directory file is implementation-defined, and 
differs radically between System V and 4.3BSD. However, routines (derived 
from 4.3BSD) for accessing directories are provided in Directory Operations 
§5.1.2 and certain constraints on the format of the information returned by 
those routines are made in Format of Directory Entries §5.1.1. 


directory entry. Throughout the document, the term link is used (about link() 
§5.3.4, for example) in describing the things that point to files from directories. 


dot. The symbolic name dot is carefully used in the standard to distinguish the 
working directory filename from period or decimal point. 


dot-dot. Historical implementations permit the use of these filenames without 
their special meanings. Such use precludes any meaningful use of these 
filenames by a Conforming POSIX Application. Therefore such use is considered 
an extension, the use of which makes an implementation non-conforming. See 
also pathname resolution §B.2.4. 


Epoch. Normally, the origin of UNIX system time is referred to as “00:00:00 
GMT, January 1, 1970.” Greenwich Mean Time is actually not a term ack- 
nowledged by the international standards community; therefore, this term, 
Epoch, is used to abbreviate the reference to the actual standard, Coordinated 
Universal Time. The concept of leap seconds is added for precision; at the time 
this standard was published, 14 leap seconds had been added since January 1, 
1970. These 14 seconds are ignored to provide an easy and compatible method 
of computing time differences. 

Most systems’ notion of “time” is that of a continuously-increasing value, so 
this value should increase even during leap seconds. However, not only do most 
systems not keep track of leap seconds, but most systems are probably not syn- 
chronized to any standard time reference. Therefore, it is inappropriate to 
require that a time represented as seconds since the Epoch precisely represent 
the number of seconds between the referenced time and the Epoch. 

It is sufficient to require that applications be allowed to treat this time as if it 
represented the number of seconds between the referenced time and the Epoch. 
It is the responsibility of the vendor of the system, and the administrator of the 
system, to ensure that this value represents the number of seconds between the 
referenced time and the Epoch as closely as necessary for the application being 
run on that system. 

It is important that the interpretation of time names and seconds since the 
Epoch values be consistent across conforming systems. That is, it is important 
that all conforming systems interpret “536 457599 seconds since the Epoch” as 
59 seconds, 59 minutes, 23 hours 31 December 1986, regardless of the accuracy 
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of the system’s idea of the current time. The expression is given to assure a con- 
sistent interpretation, not to attempt to specify the calendar. The relationship 
between tm_yday and the day of week, day of month, and month is presumed to 
be specified elsewhere, and not given in this standard. 

Consistent interpretation of seconds since the Epoch can be critical to certain 
types of distributed applications that rely on such timestamps to synchronize 
events. The accrual of leap seconds in a time standard is not predictable. The 
number of leap seconds since the Epoch will likely increase. The standard is 
more concerned about the synchronization of time between applications of astro- 
nomically short duration and the Working Group expects these concerns to 
become more critical in the future. 

Note that tm_yday is zero-based, not one-based, so the day number in the 
example above is 364. Note also that the divide is an integer divide (discarding 
remainder) as in C. 

Note also that in Chapter 8, the meaning of gmtime(), localtime(), and 
mktime() is specified in terms of this expression. However, the C Standard com- 
putes tm_yday from tm_mday, tm_mon, and tm_year in mktime(). Because it is 
stated as a (bidirectional) relationship, not a function, and because the conver- 
sion between month-day-year and day-of-year dates is presumed well known, 
and is also a relationship, this is not a problem. 

Note that the expression given will fail after the year 2099. Since the issue of 
time_t overflowing a 32-bit integer occurs well before that time, both of these 
will have to be addressed in revisions to this standard. 


FIFO special file. See pipe §B.2.3. 


file. It is permissible for an implementation-defined file type to be non-readable 
or non-writable. 


file classes. These classes correspond to the historical sets of permission bits. 
The classes are general to allow implementations flexibility in expanding the 
access mechanism for more stringent security environments. Note that a pro- 
cess is in one and only one class, so there is no ambiguity. 


filename. For now the primary responsibility for truncating filenames contain- 
ing multibyte characters must reside with the application. The /usr/group sub- 
committee for internationalization believes that in the future, the responsibility 
must shift to the kernel. For now, there needs to be time to arrive at a better 
understanding of the implications of making the kernel responsible for trunca- 
tion of multibyte file names. 

The Working Group felt it would be inadvisable to adopt character level trun- 
cation as there is no support in this standard which advises how the kernel dis- 
tinguishes between single and multibyte characters. Until that time, it must be 
incumbent upon application writers to determine where multibyte characters 
must be truncated. 
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file system. Historically the meaning of this term has been overloaded with 
two meanings: that of the complete file hierarchy §B.2.4, and that of a mount- 
able subset of that hierarchy, i.e., a mounted file system §B.2.3. The standard 
uses the term file system in the second sense, except that it is limited to the 
scope of a process (and a process’s root directory). This usage also clarifies the 
domain in which a file serial number is unique. 


*sroup file. Implementation-defined; see System Databases §B.9. 


*historical implementations. This refers to previously-existing implementa- 
tions of programming interfaces and operating systems that are related to the 
interface specified by the standard, especially to those implementations 
described by the Base Documents §B.1.3. See also Minimal Changes to His- 
torical Implementations §B.1.2.8. 


*hosted implementation. This refers to a POSIX implementation that is 
accomplished through interfaces from the POSIX services to some alternate form 
of operating system kernel services. Note that the line between a hosted imple- 
mentation and a native implementation is blurred, since most implementations 
will provide some services directly from the kernel, and others through some 
indirect path. (For example, fopen() might use open(); or mkfifo() might use 
mknod().) There is no necessary relationship between the type of implementa- 
tion and its correctness, performance, and/or reliability. 


*implementation. The term is generally used instead of its synonym, system, 
to emphasize the consequences of decisions to be made by system implementors. 
Perhaps if no options or extensions to POSIX were allowed, this usage would not 
have occurred. 

The term specific implementation is sometimes used as a synonym for imple- 
mentation. This should not be interpreted too narrowly; both terms can 
represent a relatively broad group of systems. For example, a hardware vendor 
could market a very wide selection of systems that all used the same instruction 
set, with some systems desktop models and others large multi-user minicomput- 
ers. This wide range would probably share a common POSIX operating system, 
allowing an application compiled for one to be used on any of the others; this is a 
[specific] implementation . 

However, that wide range of machines probably has some differences between 
the models. Some may have different clock rates, different file systems, dif- 
ferent resource limits, different network connections, etc., depending on their 
sizes or intended usages. Even on two identical machines, the system adminis- 
trators may configure them differently. Each of these different systems is 
known by the term a specific instance of a specific implementation. This term is 
only used in the portions of the standard dealing with run-time queries: sys- 
conf() §4.8.1 and pathconf() §5.7.1. 


*incomplete pathname. Absolute pathname §2.4 has been adequately 
defined. 
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job control. In order to understand the job control facilities in POSIX it is use- 
ful to understand how they are used by a job control cognizant shell to create 
the user interface effect of job control. 

While the job control facilities supplied by POSIX can, in theory, support dif- 
ferent types of interactive job control interfaces supplied by different types of 
shells, there is historically one particular interface that is most common (pro- 
vided by BSD C Shell). This discussion describes that interface as a means of 
illustrating how the POSIX job control facilities can be used. 

Job control allows users to selectively stop (suspend) the execution of 
processes and continue (resume) their execution at a later point. The user typi- 
cally employs this facility via the interactive interface jointly supplied by the 
terminal I/O driver and a command interpreter (shell). 

The user can launch jobs (command pipelines) in either the foreground or 
background. When launched in the foreground, the shell waits for the job to 
complete before prompting for additional commands. When launched in the 
background, the shell does not wait but immediately prompts for new com- 
mands. 

If the user launches a job in the foreground and subsequently regrets this, the 
user can type the suspend character (typically set to control-Z) which causes the 
foreground job to stop and the shell to begin prompting for new commands. The 
stopped job can be continued by the user (via special shell commands) either as 
a foreground job or as a background job. Background jobs can also be moved 
into the foreground via shell commands. 

If a background job attempts to access the login terminal (controlling termi- 
nal) it is stopped by the terminal driver and the shell is notified which, in turn, 
notifies the user. (Terminal access includes read() and certain terminal control 
functions and conditionally includes write().) The user can continue the stopped 
job in the foreground, thus allowing the terminal access to succeed in an orderly 
fashion. After the terminal access succeeds, the user can optionally move the 
job into the background via the suspend character and shell commands. 


Implementing Job Control Shells 

The above interactive interface can be accomplished using the POSIX job con- 
trol facilities in the following way. 

The key feature necessary to provide job control is a way to group processes 
into jobs. This grouping is necessary in order to direct signals to a single job 
and also to identify which job is in the foreground. (There is at most one job 
that is in the foreground on any controlling terminal at a time.) 

The concept of process groups is used to provide this grouping. The shell 
places each job in a separate process group via the setpgid() §$4.3.3 function. To 
do this, the setpgid() function is invoked by the shell for each process in the job. 
It is actually useful to invoke setpgid() twice for each process: once in the child 
process. after calling fork() to create the process but before calling exec() to 
begin execution of the program, and once in the parent shell process, after cal- 
ling fork() to create the child. The redundant invocation avoids a race condition 
by ensuring that the child process is placed into the new process group before 
either the parent or the child relies on this being the case. The process group ID 
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for the job is selected by the shell to be equal to the process ID of one of the 
processes in the job. Some shells choose to make one process in the job be the 
parent of the other processes in the job (if any). Other shells (e.g., the C Shell) 
choose to make themselves the parent of all processes in the pipeline (job). In 
order to support this latter case, the setpgid() function accepts a process group 
ID parameter since the correct process group ID cannot be inherited from the 
shell. The shell itself is considered to be a job and is the sole process in its own 
process group. 

The shell also controls which job is currently in the foreground. A foreground 
and background job differ in two ways: the shell waits for a foreground com- 
mand to complete (or stop) before continuing to read new commands, and the 
terminal I/O driver inhibits terminal access by background jobs (causing the 
processes to stop). Thus the shell must work cooperatively with the terminal I/O 
driver and have a common understanding of which job is currently in the fore- 
ground. It is the user who decides which command should be currently in the 
foreground and the user informs the shell via shell commands. The shell, in 
turn, informs the terminal I/O driver via the tcsetpgrp() §7.2.4 function. This 
indicates to the terminal I/O driver the process group ID of the foreground pro- 
cess group (job). When the current foreground job either stops or terminates, 
the shell places itself in the foreground via tcsetpgrp() before prompting for 
additional commands. Note that when a job is created the new process group 
begins as a background process group. It requires an explicit act of the shell via 
tcsetpgrp() to move a process group (job) into the foreground. 

When a process in a job stops or terminates, its parent (e.g., the shell) receives 
synchronous notification by calling the waitpid() function with the WUN- 
TRACED flag set. Asynchronous notification is also provided when the parent 
establishes a signal handler for SIGCHLD and does not specify the 
SA_NOCLDSTOP flag. Usually all processes in a job stop as a unit since the ter- 
minal I/O driver always sends job control stop signals to all processes in the pro- 
cess group. 

To continue a stopped job, the shell sends the SIGCONT signal to the process 
group of the job. In addition, if the job is being continued in the foreground, the 
shell invokes tcsetpgrp() to place the job in the foreground before sending 
SIGCONT. Otherwise the shell leaves itself in the foreground and reads addi- 
tional commands. 

There is additional flexibility in the POSIX job control facilities which allow 
deviations from the typical interface. Clearing the TOSTOP terminal flag (see 
Local Modes §7.1.2.5) allows background jobs to perform write() functions 
without stopping. The same effect can be achieved on a per-process basis by 
having a process set the signal action for SIGTTOU to SIG_IGN. 

Note that the terms job and process group can be used interchangeably. A 
login session which is not using the job control facilities can be thought of as a 
large collection of processes which are all in the same job (process group). Such 
a login session may have a partial distinction between foreground and back- 
ground processes; that is, the shell may choose to wait for some processes before 
continuing to read new commands and may not wait for other processes. How- 
ever, the terminal I/O driver will consider all these processes to be in the 
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foreground since they are all members of the same process group. 

In addition to the basic job control operations already mentioned, a job control 
cognizant shell needs to perform the following actions: 

When a foreground (not background) job stops, the shell must sample and 
remember the current terminal settings so that it can restore them later when it 
continues the stopped job in the foreground (via the tcgetattr() and tcsetattr() 
functions). 

Because a shell itself can be spawned from a shell, it must take special action 
to ensure that subshells interact well with their parent shells. 

A subshell can be spawned to perform an interactive function (prompting the 
terminal for commands) or a non-interactive function (reading commands from 
a file). When operating non-interactively, the job control shell will refrain from 
performing the job control specific actions described above. It will behave as a 
shell which does not support job control. For example, all jobs will be left in the 
same process group as the shell which itself remains in the process group esta- 
blished for it by its parent. This allows the shell and its children to be treated 
as a single job by a parent shell and they can be affected as a unit by terminal 
keyboard signals. 

An interactive subshell can be spawned from another job control cognizant 
shell in either the foreground or background. (For example, from the C Shell 
execute the command, csh &.) Before the subshell activates job control by cal- 
ling setpgid() to place itself in its own process group and tcsetpgrp() to place its 
new process group in the foreground, it needs to ensure that it has already been 
placed in the foreground by its parent. (Otherwise there could be multiple job 
control shells which simultaneously attempt to control mediation of the termi- 
nal.) To determine this, the shell retrieves its own process group via getpgrp() 
§4.3.1 and the process group of the current foreground job via tcgetpgrp() §7.2.3. 
If these are not equal, the shell sends SIGTTIN to its own process group causing 
itself to stop. When continued later by its parent, the shell repeats the process 
group check. When the process groups finally match, the shell is in the fore- 
ground and it can proceed to take control. After this point, the shell ignores all 
the job control stop signals so that it doesn’t inadvertently stop itself. 


Implementing Job Control Applications 

Most applications do not need to be aware of job control signals and opera- 
tions; the “right thing” happens by default. However, sometimes an application 
can inadvertently interfere with normal job control processing. Or an applica- 
tion may choose to overtly effect job control in cooperation with normal shell 
procedures. 

An application can inadvertently subvert job control processing by “blindly” 
altering the handling of signals. A common application error is to learn how 
many signals the system supports and to ignore or catch them all. Such an 
application makes the assumption: “I don’t know what this signal is, but I know 
the right handling action for it.” The system may initialize the handling of job 
control stop signals so that they are being ignored. This allows shells which do 
not support job control to inherit and propagate these settings and hence to be 
immune to stop signals. A job control shell will set the handling to the default 
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action and propagate this, allowing processes to stop. In doing so, the job con- 
trol shell is taking responsibility for restarting the stopped applications. If an 
application wishes to catch the stop signals itself, it should first determine their 
inherited handling states. If a stop signal is being ignored, the application 
should continue to ignore it. This is directly analogous to the recommended 
handling of SIGINT described by Kernighan and Ritchie in UNIX Programming 
— Second Edition in the UNIX Programmer’s Manual. 

If an application is reading the terminal and has disabled the interpretation 
of special characters (by clearing the ISIG flag), the terminal I/O driver will not 
send SIGTSTP when the suspend character is typed. Such an application can 
simulate the effect of the suspend character by recognizing it and sending 
SIGTSTP to its process group as the terminal driver would have done. Note that 
the signal is sent to the process group, not just to the application itself; this 
ensures that other processes in the job also stop. (Note that other processes in 
the job could be children, siblings, or even ancestors.) Another point worth not- 
ing is that applications should not assume that the suspend character is 
control-Z (or any particular value); they should retrieve the current setting at 
startup. 


Implementing Job Control Systems 

The intent in adding 4.2BSD-style job control functionality was to adopt the 
necessary 4.2BSD programmatic interface with only minimal changes to resolve 
syntactic or semantic conflicts with System V or to close recognized security 
holes. The goal was to maximize the ease of providing both conforming imple- 
mentations and Conforming POSIX Applications. 

Discussions of the changes can be found in the sections which discuss the 
specific interfaces. See sections: Wait for Process Termination §B.3.2.1, 
Terminate a Process §B.3.2.2, Signal Names §B.3.3.1, Send a Signal to a 
Process §B.3.3.2, Examine and Change Signal Action §B.3.3.4, Get Pro- 
cess Group ID §B.4.3.1, Set Process Group ID for Job Control §B.4.3.3, 
Terminal Access Control §B.7.1.1.3, and Set Foreground Process Group 
ID §B.7.2.4. 

It is only useful for a process to be affected by job control signals if it is the 
descendant of a job control shell. Otherwise, there will be nothing which contin- 
ues the stopped process. Because a job control shell is allowed, but not required, 
by the standard, an implementation must provide a mechanism which shields 
processes from job control signals when there is no job control shell. The usual 
method is for the system initialization process (typically called init), which is 
the ancestor of all processes, to launch its children with the signal handling 
action set to SIG_IGN for the signals SIGTSTP, SIGTTIN, and SIGTTOU. Thus all 
login shells start with these signals ignored. If the shell is not job control cog- 
nizant, then it should not alter this setting and all its descendants should 
inherit the same ignored settings. At the point where a job control shell is 
launched, it resets the signal handling action for these signals to be SIG_DFL for 
its children and (by inheritance) their descendants. Also, shells which are not 
job control cognizant will not alter the process group of their descendants or of 
their controlling terminal; this has the effect of making all processes be in the 
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foreground (assuming the shell is in the foreground). While this approach is 
valid, the standard added the concept of orphaned process groups to provide a 
more robust solution to this problem. All processes in a session managed by a 
shell which is not job control cognizant are in an orphaned process group and 
are protected from stopping. 

POSIX does not specify how controlling terminal access is affected by a user 
logging out (that is, by a controlling process terminating). 4.2BSD uses the 
vhangup() function to prevent any access to the controlling terminal through 
file descriptors opened prior to logout. System V does nothing to prevent con- 
trolling terminal access through file descriptors opened prior to logout (except 
for the case of the special file, /dev/tty). Some implementations choose to 
make processes immune from job control after logout (that is, such processes are 
always treated as if in the foreground); other implementations continue to 
enforce foreground/background checks after logout. Therefore, a Conforming 
POSIX Application should not attempt to access the controlling terminal after 
logout since such access is unreliable. Note that, if an implementation chooses 
to deny access to a controlling terminal after its controlling process exits, the 
standard requires a certain type of behavior (see The Controlling Terminal 
e7.4.1.3). 


*kernel. See system call. 
*library routine. See system call. 
*logical device. Implementation-defined. 


*mount point. The directory on which a mounted file system is mounted. This 
term, like mount() and umount(), was not included because it was 
implementation-defined. 


*mounted file system. See file system. 


*native implementation. This refers to an implementation of POSIX that 
interfaces directly to an operating system kernel addressed in the standard. 
See also hosted implementation §B.2.3 and cooperating implementation 
$B.2.3. A similar concept from the UNIX world is a native UNIX system, which 
would a be kernel derived from one of AT&T's UNIX products. 


*passwd file. Implementation-defined; see System Databases §B.9. 


open file description. An open file description, as it is currently named, 
“describes” how a file is being accessed. What is currently called a file descrip- 
tor is actually just an identifier or “handle;” it does not actually describe any- 
thing. 
The following alternate names were discussed: 
For open file description: 
open instance, file access description, open file information, and file 
access information. 
For file descriptor: 
file handle, file number [c.f., fileno()]. Some historical implementa- 
tions use the term file table entry. 
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orphaned process group. Historical implementations have a concept of an 
orphaned process, which is a process whose parent process has exited. When job 
control is in use, it is necessary to prevent processes from being stopped in 
response to interactions with the terminal after they no longer are controlled by 
a job control-cognizant program. Because signals generated by the terminal are 
sent to a process group and not to individual processes, and because a signal 
may be provoked by a process which is not orphaned but sent to another process 
which is orphaned, it is necessary to define an orphaned process group. The 
definition assumes that a process group will be manipulated as a group, and 
that the job control-cognizant process controlling the group is outside of the 
group and is the parent of at least one process in the group (so that state 
changes may be reported via waitpid()). Therefore, a group is considered to be 
controlled as long as at least one process in the group has a parent that is out- 
side of the process group but within the session. 

This definition of orphaned process groups ensures that a session leader’s pro- 
cess group is always considered to be orphaned, and thus it is prevented from 
stopping in response to terminal signals. 


pipe. It proved convenient to define a pipe as a special case of a FIFO even 
though historically the latter were only introduced in System III and do not 
exist at all in 4.3BSD. 


portable filename character set. The encoding of this character set is not 
specified: specifically, ASCII is not required. But the implementation must pro- 
vide a unique character code for each of the printable graphics specified by the 
standard. See also filename portability §B.2.4. 

Note that situations where characters beyond the portable filename character 
set (or simply ASCII) would be used (in a context where the portable filename 
character set or ASCII is required herein) are expected to be common. Although 
such a situation renders the use technically non-compliant, mutual agreement 
among the users of an extended character set will make such use portable 
between those users. Such a mutual agreement could be formalized as an 
optional extension to this standard. (Making it required would eliminate too 
many possible systems, as even those systems using ASCII as a base character 
set extend their character sets for Western Europe, let alone the rest of the 
world, in different ways.) 

Nothing in this standard is intended to preclude the use of extended charac- 
ters where interchange is not required or where mutual agreement is obtained. 
It has been suggested that in several places “should” be used instead of “shall.” 
Because (in the worst case) use of any character beyond the portable filename 
character set would render the program or data not portable to all possible sys- 
tems, permitting any extensions in this context defeats the purpose of the stan- 


dard. 


regular file. The standard does not intend to preclude the addition of structur- 
ing data (e.g., record lengths) in the file, as long as such data is not visible to an 
application that uses the features described in the standard. 
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root directory. This definition permits the operation of chroot(), even though 
that function is not in the standard. See also file hierarchy §B.2.4. 


*root file system. Implementation-defined. 
*root of a file system. Implementation-defined. See mount point. 


signal. The definition implies a double meaning for the term. Although a sig- 
nal is an event, common usage implies that a signal is an identifier of the class 
of event. 


*system call. The distinction between a system call and a library routine is an 
implementation detail that may differ between implementations and has thus 
been excluded from the standard. See Interface, Not Implementation 
SB.1.2.2. 


*super-user. This concept, with great historical significance to UNIX system 
users, has been replaced with the notion of appropriate privileges. 


B.2.4 General Concepts. 


extended security controls. Allowing an implementation to define extended 
security controls enables the use of this standard in environments which require 
different or more rigorous security than that provided in the standard. Exten- 
sions are allowed in two areas: privilege and file access permissions. The 
semantics of these areas have been defined to permit extensions with reason- 
able, but not exact compatibility with all existing practices. For example, the 
elimination of the super-user definition precludes identifying a process as 
privileged or not by virtue of its effective user ID. 


file access permissions. A process should not try to anticipate the result of 
an attempt to access data by a priori use of these rules. Rather, it should make 
the attempt to access data and examine the return value (and possibly errno, as 
well), or use access() §5.6.3. An implementation may include other security 
Mechanisms in addition to those specified in the standard, and an access 
attempt may fail because of those additional mechanisms even though it would 
succeed according to the rules given in this section. (For example, the user’s 
security level might be lower than that of the object of the access attempt.) The 
optional supplementary group IDs provide another reason for a process to not 
attempt to anticipate the result of an access attempt. 


file hierarchy. Though the file hierarchy is commonly regarded to be a tree, 
the standard does not define it as such for three reasons: 
(1) As noted in the standard, links may join branches. 
(2) In some network implementations, there may be no single absolute root 
directory. See pathname resolution. 
(3) With symbolic links (found in 4.3BSD), the file system need not be a tree 
or even a Directed Acyclic Graph. 
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file permissions. Examples of implementation-defined constraints that may 
deny access are mandatory labels and access control lists. 


filename portability. Traditionally, certain filenames have been reserved. 
This list includes core, /etc/passwd, etc. Care should be taken in portable 
applications to avoid these. 

Most historical implementations, including all of those described by the Base 
Documents §B.1.3, prohibit case folding in filenames, i.e., treating upper- and 
lowercase alphabetic characters as identical. However, some consider case fold- 
ing desirable 

(1) For user convenience. 

(2) For ease of implementation of the standard interface as a hosted system 
on some popular operating systems, which is compatible with the goal of 
making the standard interface Broadly Implementable §B.1.2.7. 

Variants such as maintaining case distinctions in filenames but ignoring them 
in comparisons have been suggested. Methods of allowing escaped characters of 
the case opposite the default have been proposed. 

Many reasons have been expressed for not allowing case folding, including: 

(1) No solid evidence has been produced as to whether case sensitivity or 
case insensitivity is more convenient for users. 
(2) Making case insensitivity a POSIX implementation option would be worse 
than either having it or not having it, because 
(a) More confusion would be caused among users. 
(b) Application developers would have to account for both cases in their 
code. 
(c) POSIX implementors would still have other problems with native file 
systems, such as short or otherwise constrained filenames or pathnames, 
not to mention the lack of hierarchical directory structure. 
(3) Case folding is not easily defined in many European languages, both 
because many of them use characters outside the USASCII alphabetic set, 
and because: 
(a) In Spanish the digraph 1] is considered to be a single letter, the capi- 
talized form of which may be either LI or LL depending on context. 
(b) In French the capitalized form of a letter with an accent may or may 
not retain the accent depending on the country in which it is written. 
(c) In German the sharp ess may be represented as a single character 
resembling a Greek beta (8) in lowercase but as the digraph SS in upper- 
case. 
(d) In Greek there are several lowercase forms of some letters; the one to 
use depends on its position in the word. Arabic has similar rules. 
(4) Many East Asian languages, including Japanese, Chinese, and Korean, 
do not distinguish case, and are sometimes encoded in character sets that 
use more than one byte per character. 
(5) Multiple character codes may be used on the same machine simultane- 
ously. There are several ISO character sets for European alphabets. In 
Japan, several Japanese character codes are commonly used together, some- 
times even in filenames; this is evidently also the case in China. To handle 
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case insensitivity, the kernel would have to at least be able to distinguish for 

which character sets the concept made sense. 

(6) The file system implementation historically deals only with bytes, not 

with characters, except for slash and the null byte. 

(7) The purpose of the Working Group is to standardize the common, existing 

definition (see Application Oriented §B.1.2.1) of the UNIX system pro- 

gramming interface, not to change it. Mandating case insensitivity would 

make all historical implementations non-standard. 

(8) Not only the interface, but also application programs would need to 

change, counter to the purpose of having minimal changes to existing 

application code §B.1.2.9. 

(9) At least one of the original developers of the UNIX system has expressed 

objection in the strongest terms to either requiring case insensitivity or mak- 

ing it an option, mostly on the basis that the standard should not hinder por- 

tability of application programs across related implementations in order to 

allow compatibility with unrelated operating systems. 

Two proposals were entertained regarding case folding in filenames: 

(1) Remove all wording that previously permitted case folding. 

Rationale: Case folding is inconsistent with portable filename character set 

definition and filename definition (all characters except slash and null). No 

known implementations allowing all characters except slash and null also do 

case folding. 

(2) Change “though this practice is not recommended:” to “although this 

practice is strongly discouraged.” 

Rationale: If case folding must be included in the standard, the wording 

should be stronger to discourage the practice. 

The consensus of the Working Group was in favor of proposal (1). Otherwise, 

a portable application would have to assume that case folding would occur when 
it wasn’t wanted, but that it wouldn’t occur when it was wanted. 


file times update. This section reflects the actions of historical implementa- 
tions. The times are not updated immediately, but are only marked for update 
by the functions. An implementation may update these times immediately. 

Earlier drafts had not required these times and did not clearly specify the 
time update process. However, the Working Group felt that the functionality 
provided was important. 

The accuracy of the time update values is intentionally left unspecified so that 
systems can control the bandwidth of a possible covert channel. 


pathname resolution. What the filename dot-dot refers to relative to the root 
directory is implementation-defined. In Version 7 it refers to the root directory 
itself; this is the behavior mentioned in the standard. In some networked sys- 
tems the construction /. . /hostname/ is used to refer to the root directory of 
another host, and the standard permits this behavior. 

Other networked systems use the construct //hostname for the same pur- 
pose, i.e., a double initial slash is used. Because existing applications which 
create full pathnames by taking a trunk and a relative pathname and making 
them into a single string separated by / can accidentally create networked 
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pathnames when the trunk is /, the Working Group considered prohibiting this 
practice. However, such applications can be made to conform by simply chang- 
ing to use // as a separator instead of /: 
(1) If the trunk is /, the full path name will begin with /// (the initial / and 
the separator //). This is the same as /, which is what is desired. (This is 
the general case of making a relative pathname into an absolute one by pre- 
fixing with /// instead of /.) 
(2) If the trunk is /A, the result is /A//...; since non-leading sequences of 
two or more slashes are treated as a single slash, this is equivalent to the 
desired /A/.... 
(3) If the trunk is //A, the implementation-defined semantics will apply. 
(The multiple slash rule would apply.) 

Application developers should avoid generating pathnames that start with 
“//”. Implementations are strongly encouraged to avoid using this special 
interpretation since a number of applications currently do not follow this prac- 
tice and may inadvertently generate “//...”. 

The term root directory is only defined in the standard relative to the process. 
In some implementations, there may be no absolute root directory. The initiali- 
zation of the root directory of a process is implementation-defined. 


B.2.5 Error Numbers. Checking the value of errno alone is not sufficient 
to determine the existence or type of an error, since it is not required that a suc- 
cessful function call clear errno. The variable errno should only be examined 
when the return value of a function indicates that the value of errno is meaning- 
ful. In that case, the function is required to set the variable to something other 
than zero. 

A successful function call may set the value of errno to zero, or to any other 
value (except where specifically prohibited: see mkdir() §B.5.4.1). But it is 
meaningless to do so, since the value of errno is undefined except when the 
description of a function explicitly states that it is set, and no function descrip- 
tion states that it should be set on a successful call. Most functions in most 
implementations do not change errno on successful completion. Exceptions are 
isatty() §4.7.2 and ptrace(). The latter is not in the standard, but is widely 
implemented and clears errno when called. The value of errno is not defined 
unless all signal handlers that use functions that could change errno save and 
restore it. 

The standard requires (in the Errors subsections of function descriptions) 
certain error values to be set in certain conditions because many existing appli- 
cations depend on them. Some error numbers, such as [EFAULT], are entirely 
implementation-defined and are noted as such in their description in Error 
Numbers §2.5. This section otherwise allows wide latitude to the implementa- 
tion in handling error reporting. 

All references to the term system call have been excised from the descriptions 
of errors in this section. 

Some of the Errors sections in the standard have two subsections. The first: 


“If any of the following conditions occur, the foo() function shall 
return —1 and set errno to the corresponding value:” 
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could be called the “mandatory” section. The second: 


“For each of the following conditions, when the condition is 
detected, the foo() function shall return —1 and set errno to the 
corresponding value:” 


has been known to the Working Group as the “optional” section. This latter sec- 
tion has evolved in meaning over time. Originally, it was only used for error 
conditions that could not be detected by certain hardware configurations, such 
as the [EFAULT] error, as described below. The section recently has also added 
conditions associated with optional system behavior, such as job control errors. 

Following each one-word symbolic name for an error, there is a one-line tag, 
which is followed by a description of the error. The one-line tag is merely a 
mnemonic or historical referent and is not part of the specification of the error. 
Many programs print these tags on the standard error stream (often by using 
the C Standard perror() function) when the corresponding errors are detected, 
but the standard does not require this action. 

[EFAULT] Most historical implementations do not catch an error and set 
errno when a bad address is given to the functions wait() §3.2.1, 
time() §4.5.1, or times() §4.5.2. Some implementations cannot 
reliably detect a bad address. And most systems that detect bad 
addresses will do so only for a system call §B.2.3, not for a 
library routine §B.2.3. 

[EINTR] The standard prohibits conforming implementations from res- 
tarting interrupted system calls. However, it does not require 
that [EINTR] be returned when another legitimate value may be 
substituted, e.g., a partial transfer count when read() or write() 
are interrupted. This is only given when the signal catching 
function returns normally as opposed to returns by mechanisms 
like longjmp() or siglongjmp(). 

[ENOMEM] The term main memory §B.2.3 has been eliminated from his- 
torical versions of this description as being implementation- 
defined. 

[ENOTTY] The symbolic name for this error is derived from a time when 
device control was done by ioct/() §B.7 and that operation was 
only permitted on a terminal interface. The term “TTY” is 
derived from teletypewriter, the devices to which this error ori- 
ginally applied. 

[EPIPE] This condition normally generates the signal SIGPIPE; the error 
is returned if the signal does not terminate the process. 

[EROFS] In historical implementations, attempting to wnlink() or 
rmdir() a mount point would generate an [EBUSY] error. An 
implementation could be envisioned where such an operation 
could be performed without error. In this case, if either the 
directory entry or the actual data structures reside on a read- 
only file system, [EROFS] is the appropriate error to generate. 
(For example, changing the link count of a file on a read-only 
file system could not be done, as is required by unlink(), and 
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thus an error should be reported.) 
Two error numbers, [EDOM] and [ERANGE], were added to this section pri- 
marily for consistency with the C Standard. 


B.2.6 Primitive System Data Types. Depending on which draft is con- 
sulted, a requirement that additional types defined in this section end in “_t” 
may or may not have been present. The issue of namespace pollution (see 
POSIX Symbols §B.2.8.2) decided this in favor of requiring that “_t” be used. It 
is difficult to define a type in one header file and use it in another, where that 
type is not one defined by this standard, without adding symbols to the 
namespace of the program. To allow implementors to provide their own types, 
programs which use <sys/types.h> are required by this standard to avoid sym- 
bols ending in “_t”, which permits the implementor to provide additional types. 
Because a major use of types is in the definition of structure members, which 
can (and in many cases must) be added to the structures defined in this stan- 
dard, the need for additional types is compelling. 

The types such as ushort and ulong, which are in common usage, are not 
defined in this standard (although wshort_t would be permitted as an extension). 
They can be added to <sys/types.h> using a feature test macro (see POSIX 
Symbols §2.8.2). A suggested symbol for these is _SYSIII. Similarly the types 
like u_short would probably be best controlled by _BSD. 

Some of these symbols may appear in other headers; see C Language Defin- 
itions §2.8. 

dev_t This type may be made large enough to accommodate host- 

locality considerations of networked systems. 

This type must be arithmetic. Earlier drafts allowed this to 
be non-arithmetic (such as a structure) and provided a same- 
file function for comparison. 

gid_t Some implementations had separated gid_t from uid_t before 

this standard was completed. It would be a burden for them to 
coalesce them when it was unnecessary. Additionally, it is quite 
possible that user IDs might be different than group IDs because 
the user ID might wish to span a heterogeneous network, where 
the group ID might not. 

For current implementations, the cost of having a separate 
gid_t will be only lexical. 

mode_t This type was chosen so that implementations could choose the 

appropriate integral type, and for compatibility with the 
C Standard. 4.3BSD uses unsigned short and the SVID uses 
ushort, which is the same thing. Historically, only the low- 
order sixteen bits are significant. 


nlink_t This type was introduced in place of short for st_nlink (see 
<sys/stat.h> §5.6.1) in response to an objection that short was 
too small. 

off_t This type is used only in lseek() §6.5.3, fentl() §6.5.2, and 


<sys/stat.h> §5.6.1. Many implementations would have diffi- 
culties if it were defined as anything other than long. The 
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pid_t 


uid_t 


Working Group realizes that requiring an integral type limits 
the capabilities of /seek() to four gigabytes. See /read() §B.6.4. 
Also, the C Standard supplies routines that use larger types: 
see fgetpos() §B.6.5.3 and fsetpos() §B.6.5.3. 

There has been a lot of debate about the inclusion of this sym- 
bol. Much of it is tied to the issue of the representation of a pro- 
cess ID as anumber. From the point of view of a portable appli- 
cation, process IDs should be “magic cookies” that are produced 
by calls such as fork(), and used by calls such as waitpid() or 
kill(), and which are not otherwise analyzed. (Except that sign 
is used as a flag for certain operations.) 

The concept of {PID_MAX} interacted with this. Treating PIDs 
as an opaque type both removes the requirement for {PID_MAX} 
and allows system to be more flexible in providing PIDs that 
span a large range of values, or a small one. 

Since in the general case the values in uid_t, gid_t, and pid_t 
will just be numbers, and will be potentially both large in mag- 
nitude and sparse, applications which are based on arrays of 
objects of this type are unlikely to be fully portable in any case. 
Solutions which treat them as magic cookies will be portable. 

{CHILD_MAX} precludes the possibility of a “toy” implementa- 

tion where there would only be one process. 
Before the addition of this type, the data types used to 
represent these values varied throughout the standard. The 
<sys/stat.h> §5.6.1 header defined these values as type short, 
the <passwd.h> file (now <pwd.h> §9.2.2 and <grp.h> §9.2.1) 
used an int and getuid() §4.2.1 returned an int. In response to 
a strong objection to the inconsistent definitions, the Working 
Group decided to switch all the types to uid_t. 

In practice, those historical implementations that use varying 
types of this sort can typedef uid_t to short with no serious 
consequences. 

The main problem associated with this change is a concern 
about object compatibility after structure size changes. Since 
most implementations will define uid_t as a short, the only sub- 
stantive change will be a reduction in the size of the passwd 
§9.2.2 structure. Consequently, implementations with an over- 
riding concern for object compatibility can pad the structure 
back to its current size. For that reason, this problem wasn’t 
considered critical enough to warrant the addition of a separate 
type to the standard. 

The types uid_t and gid_t are magic cookies. There is no 
{UID_MAX} defined by the standard, and no structure imposed 
on uid_t and gid_t other than that they be positive arithmetic 
types. (In fact, they could be unsigned char.) There is no max- 
imum or minimum specified for the number of distinct user or 
group IDs. 
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B.2.7. Environment Description. 


LC_+ 


PATH 


TZ 


LOGNAME 


The description of the environment variable names starting 
with the characters “LC_” acknowledges the fact that the inter- 
faces presented in the draft are not complete and may be 
extended as new international functionality is required. In the 
X3J11 draft proposal, names preceded by “LC_” are reserved in 
the name space for future categories. 

To avoid name clashes, new categories and environments 
variables will be divided into two _ classifications: 
implementation-independent and implementation-dependent. 

Implementation-independent names will have the following 
format: 


LC_NAME 


where NAME is the name of the new category and environment 
variable. Capital letters must be used for implementation- 
independent names. 

Implementation-dependent names must be in lowercase 
letter, as below: 


LC_name 


Many historical implementations of the Bourne shell do not 
interpret a trailing colon to represent the current working- 
directory, and are thus non-conforming. The C shell and the 
Korn shell conform to the standard on this point. The usual 
name of dot §2.3 may also be used to refer to the current work- 
ing directory. 

See Extensions to Time Functions §8.1.1 for an explanation 
of the format. 

4.3BSD uses the environment variable USER for this purpose. 
In most implementations, the value of such a variable is easily 
forged, so security-critical applications should rely on other 
means of determining user identity. LOGNAME is required to 
be constructed from the portable filename character set for rea- 
sons of interchange. No diagnostic condition is specified for 
violating this rule, and no requirement for enforcement exists. 
The intent of the requirement is that if extended characters are 
used, the “guarantee” of portability implied by a standard is 
voided. (See also portable filename character set §B.2.3.) 


The following environment variables have been used historically as indicated. 
However, such use was either so variant as to not be amenable to standardiza- 
tion, or to be relevant only to other facilities not specified in this standard, and 
they have therefore been excluded. They may or may not be included in future 
POSIX standards. Until then, writers of conforming applications should be 
aware that details of the use of these variables are likely to vary in different 


contexts. 
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IFS Characters used as field separators. 
MAIL System mailer information. 
PS1 Prompting string for interactive programs. 
PS2 Prompting string for interactive programs. 
SHELL The shell command interpreter name. 


B.2.8 C Language Definitions. The construct <name.h> for headers is 
also taken from the C Standard. 

B.2.8.1 Symbols From The C Standard. The reservation of identifiers 
is taken directly from the C Standard. It is quoted because it needs to be part of 
this standard, and because by quoting, if the C Standard does change, the 
requirement here will not change, which is intended. The reservation of other 
namespaces is particularly for <errno.h>. 

These identifiers may be used by implementations, particularly for feature 
test macros. Care needs to be taken to assure that implementations do not use 
feature test macro names that might be reasonably used by a standard. 

Headers being included more than once is a reasonably common practice, and 
should be carried forward from the C Standard. More significantly, having 
definitions in more than one header is explicitly permitted. Where the potential 
declaration is “benign” (the same definition twice) the declaration can be 
repeated, if that is permitted by the compiler. (This is usually true of macros, 
for example.) In those situations where a repetition is not benign (e.g. typedefs), 
conditional compilation must be used. The situation actually occurs both within 
the C Standard and within this standard: time_t should be in <sys/types.h>, 
and the C Standard mandates that it be in <time.h>. This standard requires 
using <sys/types.h> with <time.h> because of the common usage environment. 

B.2.8.2 POSIX Symbols. This section addresses the issue of “namespace 
pollution.” The C Standard requires that the namespace beyond what it 
reserves not be altered except by explicit action of the application writer. This 
section defines the actions to add the POSIX symbols for those headers where 
both the C Standard and POSIX need to define symbols. Where there are non- 
overlapping uses of headers, of course there is no problem. 

When headers are used to provide symbols, there is a potential for introducing 
symbols that the application writer cannot predict. Ideally, each header should 
only contain one set of symbols, but this is not practical for historical reasons. 
Thus the concept of feature test macros is included. This is done in a general 
way because it is expected that future additions to this standard and other 
related standards will have this same problem. (Future standards not con- 
strained by historical practice should avoid the problem by using new header 
files rather than using ones already extant.) 

This idea is split into two sections: 2.8.2.1 covers the case of the C Standard 
conformant systems, where the requirements of the C Standard are that unless 
specifically requested you will not see any other symbols, and “Common Usage,” 
where the default set of symbols is not well controlled, and backwards compati- 
bility is an issue. 

The tricky part is common usage. In the C Standard case, each feature test 
macro simply adds to the possible symbols. In common usage, _POSIX_SOURCE 
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is a special case in that it reduces the set to the sum of the C Standard and 
POSIX. (It is up to X3J11 to determine if they want a similar macro to limit the 
features to just the C Standard; the wording permits this because under those 
circumstances _POSIX_SOURCE would be just another ordinary feature test 
macro. The only order requirement is “before headers.”) 

If _POSIX_SOURCE is not defined in a common usage environment, the user 
presumably gets the same results as in previous releases. Some applications 
may today be conformant without change, so they would continue to compile as 
long aS common usage is provided. When the C Standard is the default they 
will have to change (unless they are already C Standard conformant), but this 
can be done gradually. 

Note that the net result of defining _POSIX_SOURCE at the beginning of a pro- 
gram is in either case the same: you won’t get implementation defined symbols 
unless you ask for them. (But if you don’t use -POSIX_SOURCE you may or may 
not; you get the implementation default, which is probably backwards compati- 
ble.) 

Because members of structures and unions are a limited namespace, it is not 
an issue of namespace pollution for an implementor to add fields to a structure 
or union, and that special case is excepted. 

There is also a special case for names of predefined forms. This is to permit 
adding symbols (typedefs) of the form xxx_t to <sys/types.h>, which can be used 
by structures or unions which appear in other header files. It is extremely diffi- 
cult to have these types appear only in the context where they are needed (for 
example, in the extra fields of a stat or dir structure) without this exception. 

Lastly, the standard is silent about whether additional symbols can be defined 
in headers, as long as they are under control of _POSIX_SOURCE, with the 
exception discussed above. This permits implementors to make a best judge- 
ment decision on such issues. 

There are several common environments available today where a feature test 
macro would be useful to applications programmers during the transition to 
standard conforming environments from certain common historical environ- 
ments. The following, derived from common porting bases and “pseudo- 
standards,” are suggested. (The “owners” of these various bases are generally 
fairly clear, and if these symbols are inappropriate or inaccurate they could sug- 
gest others, possibly to be included in later editions of this document.) 


__ Symbol _ Description 
_V7 Version 7 
_BSD General BSD systems. 
_BSD4_2 4.2BSD 
_BSD4_3 4.3BSD 
_SYSIII AT&T System III 
_SYSV AT&T System V.1 V.2 
Boveve AT&T System V.3 
XPGn X/OPEN Portability Guide, Issue n 


_USR_GROUP The 1984 /usr/group standard. 
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(Only symbols that are actually in the porting base or pseudo-standard should 
be enabled by these symbols.) 

Feature test macros for implementation extensions will also probably be 
required. Quite a few of these are traditionally available, but are in violation of 
the intent of namespace pollution control. These can be made conforming sim- 
ply by prefixing them with an underscore. Symbols beginning with “_POSIX” are 
strongly discouraged, as they will probably be used by later revisions of this 
standard. 

The environment for compilation has traditionally been fairly portable in his- 
torical systems, but during the transition to the C Standard there will be confu- 
sion about how to specify that a C Standard compiler is expected, as considera- 
tions of backwards compatibility will constrain many implementors from provid- 
ing a conformant environment replacing the traditional one. This concern has 
more to do with the issues of namespace than with the syntax of the language 
accepted, which is highly compatible. 

For systems which are sufficiently similar to traditional UNIX systems for this 
to make sense (e.g. those that will probably conform to P1003.2), it is suggested 
that if a compilation line of the form 


CE =) SaeH 


is provided, that the system provide an environment that is conformant with the 
C Standard, at least with respect to namespace. (It is not expected that this will 
be required in the future or that it will be formally standardized. It is suggested 
as a convention during the transition.) 

It was decided to use feature test macros, rather than the inclusion of a 
header, both because <unistd.h> was already in use and would itself have this 
problem, and because the underlying mechanism would probably have been this 
anyway, but in a less flexible fashion. 

The standard requires that headers be included in all cases, although it is not 
directly clear from the text at this point in the standard. If a function doesn’t 
need any special types, then it must be declared in <unistd.h>, as stated here. 
If it does require something special, then it has an associated header, and the 
program will not compile without that header. 

B.2.8.3 Headers and Function Prototypes. 


B.2.9 Numerical Limits. This section has been completely rewritten since 
the Trial Use Standard, in order to clarify the scope and mutability of several 
classes of limits. 

B.2.9.1 C Language Limits. See also C Language Definitions §2.8 
and POSIX and the C Standard §B.1.4. 
{CHAR_MIN} 
It is possible to tell if the implementation supports native char- 
acter comparison as signed or unsigned by comparing this limit 
to zero. 
{WORD_BIT} 
This limit has been omitted, as it is not referenced elsewhere in 
POSIX. 
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No limits are given in <limits.h> for floating point values because none of the 
functions in the standard proper use floating point values and all the functions 
that do that are imported from the C Standard by Referenced C Language 
Routines §8.1 defined in the C Standard, as are the limits that apply to the 
floating point values associated with them. 

Though limits to the addresses to system calls were proposed, it is not clear 
how to implement them for the range of systems being considered and, lacking a 
complete proposal, the Working Group determined not to attempt this at this 
time. Limits regarding hardware register characteristics were similarly pro- 
posed and not attempted. 

B.2.9.2 Minimum Values. There has been a lot of confusion about the 
minimum maxima, and when that is understood there is still a concern about 
providing ways to allocate storage based on the symbols. This is particularly 
true for those in Run-Time Invariant Values (Possibly Indeterminate) 
§2.9.4 where an indeterminate value will leave the programmer with no symbol 
to fall back upon. 

By providing explicit symbols for the minima (from the implementor’s point of 
view, or maxima from the the application’s point of view) this helps clear up a 
lot of possible confusion. Symbols are still provided for the actual value, and it 
is expected that many applications will take advantage of the larger values, but 
they need not do so unless it is to their advantage. Where the values in this sec- 
tion are adequate for the application, it should use them. These are given sym- 
bolically both because it makes the standard easier to understand and because 
the values of these symbols could change between revisions of the standard. 
Arguments to “good programming practice” also apply. 

B.2.9.3 Run-Time Increasable Values. The heading of the rightmost 
column of the table is given as “Minimum Value” rather than “Value” in order to 
emphasize that the numbers given in that column are minimal for the actual 
values a specific implementation is permitted to define in its <limits.h>. The 
values in the actual <limits.h> define, in turn, the maximum amount of a given 
resource that a Conforming POSIX Application can depend on finding when 
translated to execute on that implementation. A Conforming POSIX Application 
Using Extensions must function correctly even if the value given in <limits.h> 
is the minimum that is specified in the standard. (The application may still be 
written so that it performs more efficiently when a larger value is found in 
<limits.h>.) A conforming implementation must provide at least as much of a 
particular resource as that given by the value in the standard. An implementa- 
tion that cannot meet this requirement (a “toy implementation”) cannot be a 
conforming implementation. 

B.2.9.4 Run-time Invariant Values (Possibly Indeterminate). 

{CHILD_MAX} 
This name can be misleading. This limit applies to all processes 
in the system with the same user ID, regardless of ancestry. 
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B.2.9.5 Pathname Variable Values. 
{MAX_INPUT} 

Since the only use of this limit is in relation to terminal input 
queues, it mentions them specifically. This limit was originally 
named {MAX_CHAR} in early drafts. Application writers should 
use {MAX_INPUT} primarily as an indication of the number of 
bytes that can be written a single unit by one Conforming 
POSIX Application Using Extensions communicating with 
another via a terminal device. It is not implied that input lines 
received from terminal devices always contain {MAX_INPUT} 
bytes or fewer: an application that attempts to read more than 
{MAX_INPUT} bytes from a terminal may receive more than 
{MAX_INPUT} bytes. 

It is not obvious that {MAX_INPUT} is of direct value to the 
application writer. The existence of such a value (whatever it 
may be) is directly of use in understanding how the tty driver 
works (particularly with respect to flow control and dropped 
characters). The value can be determined by finding out when 
flow control takes effect (see the description of IXOFF in Input 
Modes §7.1.2.2). 

Understanding that the limit exists and knowing its magni- 
tude is important to making certain classes of applications work 
correctly. It seems unlikely that it would be used in an applica- 
tion, but its presence makes the standard clearer. 

{PATH_MAX} 
A Conforming POSIX Application or Conforming POSIX Applica- 
tion Using Extensions that, for example, compiles to use dif- 
ferent algorithms depending on the value of {PATH_MAX} should 
use code such as: 


#if defined (PATH MAX) && PATH MAX < 512 


#else 
#if defined(PATH MAX) /* PATH MAX >= 512 */ 


#else /* PATH MAX indeterminate */ 


#endif 
rz -seton ma 


This is because the value tends to be very large or indeter- 
minate on most historical implementations (it is arbitrarily 
large on System V). On such systems there is no way to quan- 
tify the limit, and it seems counter-productive to include an 
artificially small fixed value in <limits.h> in such cases. 
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B.2.10 Symbolic Constants. 

B.2.10.1 Symbolic Constants for the access () Function. 

B.2.10.2 Symbolic Constants for the /seek () Function. 

B.2.10.3 Compile-Time Symbolic Constants for Portability Specifi- 
cations. Related material appeared in an appendix of the Trial Use Standard. 
The purpose there was to allow an application developer to have a chance to 
determine whether a given application would run (or run well) on a given imple- 
mentation. To this purpose has been added that of simplifying development of 
verification suites (see Verification Testing §A.2.4) for the standard. The con- 
stants given here were originally proposed for a separate file, <posix.h>, but 
the Working Group decided that they should appear in <unistd.h> along with 
other symbolic constants. 

B.2.10.4 Execution-Time Symbolic Constants for Portability 
Specifications. Without the addition of {_POSIX_NO_TRUNC} and 
{_PC_NO_TRUNC} to this list, the standard says nothing about the effect of a 
pathname component longer than {NAME_MAX}. There are only two effects in 
common use in implementations: truncation, or an error. It is desirable to limit 
allowable behavior to these two cases. It is also desirable to permit applications 
to determine what an implementation’s behavior is, because services that are 
available with one behavior may be impractical to provide with the other. How- 
ever, since the behavior may vary from one file system to another, it may be 
necessary to use pathconf() to resolve it. 


B.3 Process Primitives. The Working Group considered enumerating all 
characteristics of a process that the standard defines, and describing each func- 
tion in terms of its effects on those characteristics, rather than English text. 
This is quite different from any known descriptions of existing implementations, 
and it was not certain that this could be done adequately and completely enough 
to produce a usable standard. Providing such descriptions in addition to the 
text was also considered. This was not done because it would provide at best 
two redundant descriptions, and more likely two descriptions with subtle incon- 
sistencies. 


B.3.1 Process Creation and Execution. Running a new program takes 
two steps. First the existing process (the parent) calls the fork() function, pro- 
ducing a new process (the child) which is a copy of itself. One of these processes 
(normally, but not necessarily, the child) then calls one of the exec functions to 
overlay itself with a copy of the new process image. 

If the new program is to be run synchronously (the parent suspends execution 
until the child completes), the parent process then uses either the wait() or 
waitpid() §3.2.1 function. If the new program is to be run asynchronously, it 
does not suffice to simply omit the wait() or waitpid() call, because after the 
child terminates it continues to hold some resources until it is waited for. A 
common way to produce (“spawn”) a descendant process that does not need to be 
waited on is to fork() to produce a child and wait() on the child. The child 
forks again to produce a grandchild. The child then exits and the parent’s 
wait() returns. The grandchild is thus disinherited by its grandparent. 
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A simpler method (from the programmer’s point of view) of spawning is to do 
system("something &"); 


However, this depends on features of a process (the shell) that are outside the 
scope of the present standard, although they are currently being addressed by 
the 1003.2 Working Group. 

B.3.1.1 Process Creation. Many existing implementations have timing 
windows where a signal sent to a process group (e.g. an interactive SIGINT) just 
prior to or during execution of fork() is delivered to the parent following the 
fork() but not the child, because the fork() code clears the child’s set of pending 
signals. It is not the intention of this standard to require, or even permit, this 
behavior. However, it is pragmatic to expect that problems of this nature may 
continue to exist in implementations that appear to conform to the standard and 
pass available verification suites. The Trial Use Standard mentioned this 
behavior in a Note that was not intended to be part of the standard, but gave 
the appearance of permitting the behavior; this Note has been removed. This 
behavior is only a consequence of the implementation failing to make the inter- 
val between signal generation and delivery totally invisible. From the 
application’s perspective, a fork() call should appear atomic. A signal that is 
generated prior to the fork() should be delivered prior to the fork(). A signal 
sent to the process group after the fork() should be delivered to both parent and 
child. The implementation might actually initialize internal data structures 
corresponding to the child’s set of pending signals to include signals sent to the 
process group during the fork(). Since the fork() call can be considered as 
atomic from the application’s perspective, from that view the set would be ini- 
tialized as empty and such signals would have arrived after the fork(). See also 
Signal Generation and Delivery §B.3.3.1.2. 

One approach that has been suggested to address the problem of signal inher- 
itance across fork() is to add an [EINTR] error which would be returned when a 
signal is detected during the call. While this is preferable to losing signals, it 
was not considered as good a fix as possible. Although it is not recommended for 
this purpose, such an error would be an allowable extension for an implementa- 
tion. 

The [ENOMEM] error value is reserved for those implementations that detect 
and distinguish such a condition. This condition occurs when an implementa- 
tion detects that there is not enough memory to create the process. This is 
intended to be returned when [EAGAIN] in not appropriate because there can 
never be enough memory (either primary or secondary storage) to perform the 
operation. Because fork() duplicates an existing process, this must be a condi- 
tion where there is sufficient memory for one such process, but not for two. 
Many existing implementations actually return [ENOMEM] due to temporary 
lack of memory, a case that is not generally distinct from [EAGAIN] from the 
perspective of a portable application. 

Part of the reason for including the optional error [ENOMEM] is because the 
SVID specifies it and it should be reserved for the error condition specified there. 
The condition is not applicable on many implementations. 
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B.3.1.2 Execute a File. The use of ellipses (...) in the Synopsis entries 
for execl(), execle(), and execlp() is not intended to be strict C language syntax, 
but to represent a concept that cannot be expressed fully in C. 

The Trial Use Standard required that the value of argc passed to main() be 
“one or greater.” This was driven by the same requirement in drafts of the 
C Standard. In fact, traditional implementations have passed a value of zero 
when no arguments are supplied to the caller of the exec functions. This 
requirement was removed from the C Standard and subsequently removed from 
this standard as well. Note however that the wording of this standard, in par- 
ticular the use of the word “should,” requires a Strictly Conforming POSIX 
Application (see Language-Dependent Services for the C Programming 
Language §2.2.3) to pass at least one argument to the exec function, thus 
guaranteeing than argc be one or greater when invoked by such an application. 
In fact this is good practice, since many existing applications reference argu [0] 
without first checking the value of argc. 

Note that the requirement on a Strictly Conforming POSIX Application also 
states that the value passed as the first argument be a filename associated with 
the process being started. Although some existing applications pass a path- 
name rather than a filename in some circumstances, a filename is more gen- 
erally useful, since the common usage of argu[0] is in printing diagnostics. In 
some cases the filename passed is not the actual filename of the file; for example 
many implementations of the login utility use a convention of prefixing a 
hyphen (—) to the actual filename, which indicates to the command interpreter 
being invoked that it is a “login shell.” 

Some systems can exec shell scripts. This functionality is outside the scope of 
this standard, since it requires standardization of the command interpreter 
language of the script and/or where to find a command interpreter. These fall in 
the domain of the P1003.2 standard. However, it is important that this stan- 
dard neither require nor preclude any reasonable implementation of this 
behavior. In particular, the description of the [ENOEXEC] error is intended to 
permit implementations discretion on whether to give this error for shell 
scripts. 

One common existing implementation is that the execl(), execu (), execle(), and 
execve() functions return an [ENOEXEC] error for any file not recognizable as an 
executable, including a shell script. When the execlp() and execup() functions 
encounter such a file, they assume the file to be a shell script and invoke a 
known command interpreter to interpret such files. These implementations of 
execup() and execlp() only give the [ENOEXEC] error in the rare case of a prob- 
lem with the command interpreter’s executable file. Because of these imple- 
mentations the [ENOEXEC] error is not mentioned for execlp() or execup(), 
although implementations can still give it. 

Another way that some existing implementations handle shell scripts is by 
recognizing the first two bytes of the file as ASCII #! and using the remainder 
of the first line of the file as the name of the command interpreter to execute. 

Some implementations provide a third argument to main() called enup. This 
is defined as a pointer to the environment. The C Standard specifies main() to 
be invoked with two arguments, so implementations must support applications 
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written this way. Since this standard defines the global variable environ, which 
is also provided by existing implementations and can be used anywhere enup 
could be used, there is no functional need for the enup argument. Furthermore, 
application writers are usually better off using the getenv() function than 
accessing the environment directly via either enup or environ. Implementations 
are required to support the two-argument calling sequence, but this does not 
prohibit an implementation from supporting envp as an optional, third argu- 
ment. 

The standard specifies that signals set to SIG_LIGN remain set to SIG_IGN, and 
that the process signal mask be unchanged across an exec. This is consistent 
with traditional implementations, and it permits some useful functionality, such 
as the nohup command. However, it should be noted that many existing appli- 
cations wrongly assume that they start with certain signals set to the default 
action and/or unblocked. In particular, applications written with a simpler sig- 
nal model that does not include blocking of signals, such as the one in the 
C Standard, may not behave properly if invoked with some signals blocked. 
Therefore it is best not to block or ignore signals across execs without explicit 
reason to do so, and especially not to block signals across execs of arbitrary (not 
closely co-operating) programs. 

If {_POSIX_SAVED_IDS} is defined, the exec functions always save the value of 
the effective user ID and effective group ID of the process at the completion of 
the exec, whether or not the set-user-ID or the set-group-ID bit of the process 
image file is set. 

[E2BIG] The limit {ARG_MAX} applies not just to the size of the argu- 
ment list, but to the sum of that and the size of the environment 
list. 

[EFAULT] Some existing systems return [EFAULT}] rather than 
[ENOEXEC] when the new process image file is corrupted. They 
are non-conforming. 

[ENAMETOOLONG] 

Since the file pathname may be constructed by taking elements 
in the PATH variable and putting them together with the 
filename, the [ENAMETOOLONG] condition could also be 
reached this way. 

[ETXTBSY] The error [ETXTBSY] was considered too implementation- 
dependent to include. System V returns this error when the 
executable file is currently open for writing by some process. 
The standard neither requires nor prohibits this behavior. 

Other systems (such as System V) may return [EINTR] from exec. This is not 
addressed by the standard, but implementations may have a window between 
the call to exec and the time that a signal could cause one of the exec calls to 
return with [EINTR]. 


B.3.2 Process Termination. The Trial Use Standard drew a different dis- 
tinction between normal and abnormal process termination. Abnormal termina- 
tion was caused only by certain signals, and resulted in implementation-defined 
“actions,” as discussed below. Subsequent drafts of the standard distinguished 
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three types of termination: normal termination (as in the current standard), 
“simple abnormal termination,” and “abnormal termination with actions.” 
Again the distinction between the two types of abnormal termination was that 
they were caused by different signals and that implementation-defined actions 
would result in the latter case. Given that these actions were completely 
implementation-defined, the standard was only saying when they could occur 
and how their occurrence could be detected, but not what they were. This was 
of little or no use to portable applications, and thus the distinction was dropped 
from the standard. 

The implementation-defined actions usually include, in most historical imple- 
mentations, the creation of a file named core in the current working directory 
of the process. This file contains an image of the memory of the process, 
together with descriptive information about the process, perhaps sufficient to 
reconstruct the state of the process at the receipt of the signal. 

There is a potential security problem in creating a core file if the process was 
set-user-ID and the current user is not the owner of the program, if the process 
was set-group-ID and none of the user’s groups match the group of the program, 
or if the user does not have permission to write in the current directory. In this 
situation, an implementation either should not create a core file or should 
make it unreadable by the user. 

Despite the silence of the standard on this feature, applications are advised 
not to create files named core because of potential conflicts in many implemen- 
tations. Some historical implementations use a different name than core for 
the file, such as by appending the process ID to the filename. 

B.3.2.1 Wait for Process Termination. A call on the wait() or wait- 
pid() function only returns status on an immediate child process of the calling 
process, i.e., a child that was produced by a single fork() §3.1.1 call (perhaps fol- 
lowed by an exec §3.1.2 or other function calls) from the parent. If a child pro- 
duces grandchildren by further use of fork(), none of those grandchildren nor 
any of their descendants will affect the behavior of a wait() from the original 
parent process. Nothing in the standard prevents an implementation from pro- 
viding extensions that permit a process to get status from a grandchild or any 
other process, but a process that does not use such extensions must be 
guaranteed to see status from only its direct children. 

The waitpid() function is provided for three reasons. One is to support job 
control (see Signals §B.3.3). The second is to permit a non-blocking version of 
the wait() function. The third is to permit a library routine, such as system() or 
pclose(), to wait for its children without interfering with other terminated chil- 
dren that have not been waited for. 

The first two of these facilities are based on the wait3() function provided by 
4.3BSD. The interface uses the options argument, which is identical to an argu- 
ment to wait3(). The WUNTRACED flag is used only in conjunction with job con- 
trol on systems supporting that option. Its name comes from 4.3BSD, and refers 
to the fact that there are two types of stopped process in that implementation: 
processes being traced via the ptrace() debugging facility, and (untraced) 
processes stopped by job control signals. Since ptrace() is not part of this stan- 
dard, only the second type is relevant. The working group chose to retain the 
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name WUNTRACED because its usage is the same, even though the name is not 
intuitively meaningful in this context. 

The third reason for the waitpid() function is to permit independent sections 
of a process to spawn and wait for children without interfering with each other. 
For example, consider the problem that the IEEE Std 1003.2 working group 
addressed: 


stream = popen("/bin/true") ; 
(void) system("Sleep 100"); 
(void) pclose(stream) ; 


On all traditional implementations, the final pclose() will fail to reap the wait 
status of the popen(). 

The status values are retrieved by macros rather than being given as specific 
bit encodings as given in most historical implementations and thus expected by 
existing programs. This was necessary to eliminate a limitation on the number 
of signals an implementation can support that was inherent in the traditional 
encodings. The standard does require that a status value of zero correspond to a 
process calling _exit(Q), as this is the most common encoding expected by exist- 
ing programs. Some of the macro names were adopted from 4.3BSD. 

These macros syntactically operate on an arbitrary integer value. The 
behavior is undefined unless that value is one stored by a successful call to 
wait() or waitpid() in the location pointed to by the stat_loc argument. An ear- 
lier specification attempted to make this clearer by specifying each argument as 
«xstat_loc rather than stat_val. However, that did not follow the conventions of 
other specifications in the standard or traditional usage. It also could have 
implied that the argument to the macro must literally be *stat_loc; in fact that 
value can be stored or passed as an argument to other functions before being 
interpreted by these macros. 

The extension that affects wait() and waitpid() and is common in traditional 
implementations is the ptrace() function. It is called by a child process and 
causes that child to stop and return status that appears identical to the status 
indicated by WIFSTOPPED(). The status of ptraced children is traditionally 
returned regardless of the WUNTRACED flag (or by the wait() function). Most 
applications do not need to concern themselves with such extensions, because 
they have control over what extensions they or their children use. However, 
applications, such as command interpreters, that invoke arbitrary processes 
may see this behavior when those arbitrary processes misuse such extensions. 

Implementations that support core file creation or other implementation- 
defined actions on termination of some processes traditionally provide a bit in 
the status returned by wait() to indicate that such actions have occurred. 

B.3.2.2. Terminate a Process. Most C language programs should use 
the exit() function rather than _exit(). 

The function _exit() is defined here instead of exit() because the C Standard 
defines the latter to have certain characteristics that are beyond the scope of the 
present standard, specifically the flushing of buffers on open files and the use of 
atexit(). See The C Language and X3J11§B.1.2.4. There are several public 
domain implementations of atexit() which may be of use to interface 
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implementors who wish to incorporate it. 

It is important that the consequences of process termination as described in 
this section occur regardless of whether the process called _exit() (perhaps 
indirectly through exit()) or instead was terminated due to a signal or for some 
other reason. Note that in the specific case of exit() this means that the status 
argument to exit() is treated the same as the status argument to _exit(). See 
also Process Termination §B.3.2. 

A language other than C may have other termination primitives than the C 
language exit() function, and programs written in such a language should use 
its native termination primitives, but those should have as part of their function 
the behavior of _exit() as described in this section. Implementations in 
languages other than C are outside the scope of the present standard, however. 

As required by X3J11, using return from main() §3.1.2 is equivalent to cal- 
ling exit() with the same argument value. Also, reaching the end of the main() 
function is equivalent to using exit() with an unspecified value. 

A value of zero (or EXIT_SUCCESS, which is required to be zero in Refer- 
enced C Language Routines §8.1) for the argument status conventionally 
indicates successful termination. This corresponds to the specification for exit() 
in the C Standard. The convention is followed by utilities such as make and 
various shells, which interpret a zero status from a child process as success. For 
this reason, applications should not call exit(0) or _exit(0) when they terminate 
unsuccessfully, for example in signal-catching functions. 

Historically, the implementation-dependent process that inherits children 
whose parents have terminated without waiting on them is called init, and 
has process ID 1. 

The sending of a SIGHUP to the foreground process group when a controlling 
process terminates corresponds to somewhat different existing implementa- 
tions. In System V the kernel sends a SIGHUP on termination of (essentially) a 
controlling process. In 4.2BSD, the kernel does not send SIGHUP in a case like 
this, but the termination of a controlling process is usually noticed by a system 
daemon which arranges to send a SIGHUP to the foreground process group with 
the vhangup() function. However, in 4.2BSD, due to the behavior of shells that 
support job control, the controlling process is usually a shell with no other 
processes in its process group. Thus a change to make _exit() behave this way 
in such systems should not cause problems with existing applications. 

The termination of a process may cause a process group to become orphaned 
in either of two ways. The connection of a process group to its parent(s) outside 
of the group depends on both the parents and their children. Thus, a process 
group may be orphaned by the termination of the last connecting parent process 
outside of the group or by the termination of the last direct descendant of the 
parent process(es). In either case, if the termination of a process causes a pro- 
cess group to become orphaned, processes within the group are disconnected 
from their job control shell, which no longer has any information on the 
existence of the process group. Stopped processes within the group would lan- 
guish forever. In order to avoid this problem, newly-orphaned process groups 
that contain stopped processes are sent a SIGHUP signal and a SIGCONT signal 
to indicate that they have been disconnected from their session. The SIGHUP 
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signal causes the process group members to terminate unless they are catching 
or ignoring SIGHUP. Under most circumstances, all of the members of the pro- 
cess group are stopped if any of them are stopped. 

The action of sending a SIGHUP and a SIGCONT signal to members of a 
newly-orphaned process group is similar to the action of 4.2BSD, which sends 
SIGHUP and SIGCONT to each stopped child of an exiting process. If such chil- 
dren exit in response to the SIGHUP, any additional descendants receive similar 
treatment at that time. In POSIX, the signals will be sent to the entire process 
group at the same time. Also, in POSIX but not in 4.2BSD, stopped processes 
may be orphaned but may be members of a process group that is not orphaned; 
therefore, the action taken at _exit() must consider processes other than child 
processes. 


B.3.3 Signals. Signals, as defined in the Trial Use Standard, and in Ver- 
sion 7, System III, the 1984 /usr/group Standard, and System V (except very 
recent releases), have shortcomings which make them unreliable for many 
application uses. Several objections were voiced against the Trial Use Standard 
because of this. Therefore a new signal mechanism, based very closely on the 
one of 4.2BSD and 4.3BSD, was added to the standard. With the exception of one 
feature (see item 4 below and also sigpending() §3.3.6), it is possible to imple- 
ment the POSIX interface as a simple library veneer on top of 4.3BSD. There are 
also a few minor aspects of the underlying 4.3BSD implementation (as opposed 
to the interface) that would also need to change to conform to the standard. 

The major differences from the BSD mechanism are: 

(1) Signal mask type. BSD uses the type int to represent a signal mask, 
thus limiting the number of signals to the number of bits in an int (typically 
thirty-two). The new standard instead uses a defined type for signal masks. 
Because of this change, the interface is significantly different than in BSD 
implementations, although the functionality and potentially the implementa- 
tion are very similar. 

(2) Restarting system calls. Unlike all previous historical implementa- 
tions, 4.2BSD restarts some interrupted system calls rather than returning 
an error with errno set to [EINTR] after the signal-catching function returns. 
This change caused problems for some existing application code. 4.3BSD and 
other systems derived from 4.2BSD allow the application to choose whether 
system calls are to be restarted. The standard (in sigaction() §3.3.4) does not 
require restart of functions, because it was not clear that the semantics of 
system call restart in any existing implementation were useful enough to be 
of value in a standard. Implementors are free to add such mechanisms as 
extensions. 

(3) Signal stacks. The 4.2BSD mechanism includes a function sigstack(). 
The 4.3BSD mechanism includes this and a function sigreturn(). No 
equivalent is included in the standard because these functions are not port- 
able, and no sufficiently portable and useful equivalent has been identified. 
See also Non-local Jumps §8.4. 

(4) Pending signals. The sigpending() §3.3.6 function is the sole new sig- 
nal operation introduced in the standard. It was requested by some 
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members of the Working Group and was seen as a simple and useful feature. 

The Working Group considered making reliable signals optional. However, 
the consensus was that this would hurt application portability, as a large per- 
centage of applications using signals can be hurt by the unreliable aspects of 
traditional implementations of the signal() mechanism defined by the 
C Standard. This unreliability stems from the fact that the signal action is reset 
to SIG_DFL before the user’s signal-catching routine is entered. The C Standard 
does not require this behavior, but does explicitly permit it, and most existing 
implementations behave this way. 

For example, an application that catches the SIGINT signal using signal() 
could be terminated with no chance to recover when two such signals arrive suf- 
ficiently close in time (e.g., when an impatient user types the INTR character 
twice in a row on a busy system). Although the C Standard no longer requires 
this unreliable behavior, many existing implementations, including System V, 
will reset the signal action to SIG_DFL. For this reason, the Working Group 
strongly recommends that the signal() function not be used by POSIX conform- 
ing applications. Implementations should also consider blocking signals during 
the execution of the signal-catching function instead of resetting the action to 
SIG_DFL, but backward compatibility considerations will most likely prevent 
this from becoming universal. 

Most traditional implementations do not queue signals, i.e., a process’s signal 
handler is invoked once, even if the signal has been generated multiple times 
before it is delivered. A notable exception to this is SIGCLD which, in System V, 
is queued. The Working Group decided to neither require nor prohibit the 
queueing of signals. See Signal Generation and Delivery §3.3.1.2. It is 
expected that a future Realtime Extension to this standard (see Realtime 
Extensions §A.2.5) will address the issue of reliable queueing of event notifica- 
tion. 

B.3.3.1 Signal Concepts. 

B.3.3.1.1 Signal Names. The restriction on the actual type used for 
sigset_t is intended to guarantee that these objects can always be assigned, have 
their address taken, and be passed as parameters by value. It is not intended 
that this type be a structure including pointers to other data structures, as that 
could impact the portability of applications performing such operations. A rea- 
sonable implementation could be a structure containing an array of some 
integer type. 

The signals described in the document must have unique values so that they 
may be named as parameters of case statements in the body of a C language 
switch clause. However, implementation-defined signals may have values that 
overlap with each other or with signals specified in this document. An example 
of this is SIGABRT, which traditionally overlaps some other signal, such as 
SIGIOT. 

SIGKILL, SIGTERM, SIGUSR1, and SIGUSR2 are ordinarily generated only 
through the explicit use of the Rill() function, although some implementations 
generate SIGKILL under extraordinary circumstances. SIGTERM is traditionally 
the default signal sent by the kil1 command. 
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The signals SIGBUS, SIGEMT, SIGIOT, SIGTRAP, and SIGSYS were omitted 
from the standard because their behavior is implementation-dependent and 
could not be adequately categorized. Conforming implementations may deliver 
these signals, but must document the circumstances under which they are 
delivered and note any restrictions concerning their delivery. The signals 
SIGFPE, SIGILL, and SIGSEGV are similar in that they also generally result only 
from programming errors. They were included in the standard because they do 
indicate three relatively well categorized conditions. They are all defined by the 
C Standard, and thus would have to be defined by any system with a 
C Standard binding, even if not explicitly included in this standard. 

There is very little if anything that a Conforming POSIX Application can do by 
catching, ignoring, or masking any of the signals SIGILL, SIGTRAP, SIGIOT, 
SIGEMT, SIGBUS, SIGSEGV, SIGSYS, or SIGFPE. They will generally be gen- 
erated by the system only in cases of programming errors. While it may be 
desirable for some robust code (e.g., a library routine) to be able to detect and 
recover from programming errors in other code, these signals are not nearly suf- 
ficient for that purpose. One portable use that does exist for these signals is 
that a command interpreter can recognize them as the cause of a process’s ter- 
mination (with wait()) and print an appropriate message. The mnemonic tags 
for these signals are derived from their PDP-11 origin. 

The signals SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, and SIGCONT are pro- 
vided for job control and are unchanged from 4.2BSD. The signal SIGCHLD is 
also typically used by job control shells to detect children which have terminated 
or, as in 4.2BSD, stopped. See also Examine and Change Signal Action 
Seo 

Some implementations, including System V, have a signal named SIGCLD 
which is similar to SIGCHLD in 4.2BSD. It is the intention of the standard to 
permit implementations to have a single signal with both names. The standard 
carefully specifies ways in which portable applications can avoid the semantic 
differences between the two different implementations. The name SIGCHLD 
was chosen for the standard because most current application usage of it can 
remain unchanged in conforming applications. SIGCLD in System V has more 
cases of semantics which the standard does not specify, and thus applications 
using it are more likely to require changes in addition to the name change. 

Some implementations that do not support job control may nonetheless imple- 
ment SIGCHLD. Similarly, such an implementation may choose to implement 
SIGSTOP. Since the standard requires that symbolic names always be defined 
(with the exception of certain names in <limits.h> §2.9 and <unistd.h> §2.10), 
a portable method of determining, at run-time, whether an optional signal is 
supported is to call the sigaction() function with NULL act and oact arguments. 
A successful return indicates that the signal is supported. Note that if sysconf() 
shows that job control is present, then all of the optional signals shall also be 
supported. 

The signals SIGUSR1 and SIGUSR2 are commonly used by applications for 
notification of exceptional behavior and are described as “reserved as 
application-defined” so that such use is not prohibited. Implementations should 
not generate SIGUSR1 or SIGUSR2, except when explicitly requested by ill() 
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§3.3.2. It is recommended that libraries not use these two signals, as such use 
in libraries could interfere with their use by applications calling the libraries. If 
such use is unavoidable it should be documented. It is prudent for non-portable 
libraries to use non-standard signals to avoid conflicts with use of standard sig- 
nals by portable libraries. 

The Trial Use Standard distinguished which signals do or don’t cause 
“implementation-defined actions” as part of abnormal termination as their 
default action on delivery. See Process Termination §B.3.2.. 

There is no portable way for an application to catch or ignore non-standard 
signals. Some implementations define the range of signal numbers, so applica- 
tions can install signal catching functions for all of them. Unfortunately, 
implementation-defined signals often cause problems when caught or ignored by 
applications that do not understand the reason for the signal. While the desire 
exists for an application to be more robust by handling all possible signals (even 
those only generated by Aill()), no existing mechanism was found to be suffi- 
ciently portable to include in the standard. The value of such a mechanism, if 
included, would be diminished given that SIGKILL would still not be catchable. 

B.3.3.1.2 Signal Generation and Delivery. The terms defined in 
this section are not used consistently in documentation of existing systems. 
Each signal can be considered to have a lifetime beginning with generation and 
ending with delivery. The Working Group considered defining delivery to 
exclude ignored signals, but the current definitions were chosen as more uni- 
form. 

Implementations should deliver unblocked signals as soon after they are gen- 
erated as possible. However, it is difficult for the standard to make specific 
requirements about this, beyond those in Rill() §3.3.2 and sigprocmask() §3.3.5. 
Even on systems with prompt delivery, scheduling of higher priority processes is 
always likely to cause delays. 

In general, the interval between the generation and delivery of unblocked sig- 
nals cannot be detected by an application. Thus, references to pending signals 
generally apply to blocked, pending signals. 

In the 4.3BSD system signals that are blocked and set to SIG_IGN are dis- 
carded immediately upon generation. For a signal that is ignored as its default 
action, if the action is SIG_DFL and the signal is blocked, a generated signal 
remains pending. In the 4.1BSD system and in System V Release 3, two other 
implementations that support a somewhat similar signal mechanism, all 
ignored, blocked signals remain pending if generated. Because it is not nor- 
mally useful for an application to simultaneously ignore and block the same sig- 
nal, it was unnecessary for the standard to specify behavior that would invali- 
date any of the existing implementations. 

There is one case in some existing implementations where an unblocked, 
pending signal does not remain pending until it is delivered. In the System V 
implementation of signal(), pending signals are discarded when the action is set 
to SIG_DFL or a signal-catching routine (as well as to SIG_IGN). Except in the 
case of setting SIGCHLD to SIG_DFL, implementations that do this do not con- 
form completely to the standard. Some earlier drafts of the standard explicitly 
stated this, but these statements were redundant due to the requirement that 
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functions defined by the standard not change attributes of processes defined by 
the standard except as explicitly stated (see Process Primitives §3). 

The standard specifically states that the order in which multiple, simultane- 
ously pending signals are delivered is unspecified. This order has not been 
explicitly specified in traditional implementations, but has remained quite con- 
sistent and been known to those familiar with the implementations. Thus there 
have been cases where applications (usually system utilities) have been written 
with explicit or implicit dependencies on this order. Implementors and people 
porting existing applications may need to be aware of such dependencies. 

When there are multiple pending signals that are not blocked, implementa- 
tions should arrange for the delivery of all signals at once if possible. Some 
implementations stack calls to all pending signal-catching routines, making it 
appear that each signal-catcher was interrupted by the next signal. In this 
case, the implementation should ensure that this stacking of signals does not 
violate the semantics of the signal masks established by sigaction(). Other 
implementations process at most one signal when the operating system is 
entered, with remaining signals saved for later delivery. Although this practice 
is in widespread use, the Working Group did not wish to standardize, nor neces- 
sarily endorse, this behavior. In either case, implementations should attempt to 
deliver signals associated with the current state of the process (e.g., SIGFPE) 
before other signals if possible. 

In 4.2BSD and 4.38BSD it is not permissible to ignore or explicitly block 
SIGCONT. The reason is that, if blocking or ignoring this signal prevented it 
from continuing a stopped process, such a process could never be continued 
(only killed by SIGKILL). However, 4.2BSD and 4.3BSD do block SIGCONT dur- 
ing execution of its signal-catching function when it is caught, creating exactly 
this problem. At one time the working group considered disallowing catching 
SIGCONT as well as ignoring and blocking it, but this limitation led to objec- 
tions. The consensus was to require that SIGCONT always continue a stopped 
process when generated. This removed the need to disallow ignoring or explicit 
blocking of the signal; note that SIG_LIGN and SIG_DFL are equivalent for 
SIGCONT. 

B.3.3.1.3 Signal Actions. Earlier drafts of the standard mentioned 
SIGCONT as a second exception to the rule that signals are not delivered to 
stopped processes until continued. Because the standard now specifies that 
SIGCONT causes the stopped process to continue when it is generated, delivery 
of SIGCONT is not prevented because a process is stopped, even without an 
explicit exception to this rule. 

Ignoring a signal by setting the action to SIG_IGN (or SIG_DFL for signals 
whose default action is to ignore) is not the same as installing a signal-catching 
function that simply returns. Invoking such a function will interrupt certain 
system functions that block processes (e.g. wait(), sigsuspend(), pause(), read(), 
write()), while ignoring a signal has no such effect on the process. 

Traditional implementations discard pending signals when the action is set to 
SIG_IGN. However, they do not always do the same when the action is set to 
SIG_DFL and the default action is to ignore the signal. The standard requires 
this for the sake of consistency and also for completeness, since the only signal 
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this applies to is SIGCHLD and the standard disallows setting its action to 
SIG_IGN. 

The specification of the effects of SIG_LIGN on SIGCHLD as implementation- 
defined permits but does not require the System V effect of causing terminating 
children to be ignored by wait() §3.2.1. Yet it permits SIGCHLD to be effectively 
ignored in an implementation-independent manner by use of SIG_DFL. 

Some implementations (System V, for example) assign different semantics for 
SIGCLD depending on whether the action is set to SIG_IGN or SIG_DFL. Since 
the standard requires that the default action for SIGCHLD be to ignore the sig- 
nal, applications should always set the action to SIG_DFL in order to avoid 
SIGCHLD. 

Some implementations (System V, for example) will deliver a SIGCLD signal 
immediately when a process establishes a signal-catching function for SIGCLD 
when that process has a child that has already terminated. Other implementa- 
tions, such as 4.3BSD, do not generate a new SIGCHLD signal in this way. In 
general, a process should not attempt to alter the signal action for the SIGCHLD 
signal while it has any outstanding children. However, it is not always possible 
for a process to avoid this; for example shells sometimes start up processes in 
pipelines with other processes from the pipeline as children. Processes that can- 
not ensure that they have no children when altering the signal action for 
SIGCHLD thus need to be prepared for, but not depend on, generation of an 
immediate SIGCHLD signal. 

The default action of the stop signals (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) 
is to stop a process that is executing. If a stop signal is delivered to a process 
that is already stopped, it has no effect. In fact, if a stop signal is generated for 
a stopped process whose signal mask blocks the signal, the signal will never be 
delivered to the process, since the process must receive a SIGCONT, which dis- 
cards all pending stop signals, in order to continue executing. 

The SIGCONT signal shall continue a stopped process, even if SIGCONT is 
blocked (or ignored). However, if a signal-catching routine has been established 
for SIGCONT, it will not be entered until SIGCONT is unblocked. 

If a process in an orphaned process group stops, it is no longer under the con- 
trol of a job control shell and hence would not normally ever be continued. 
Because of this, orphaned processes that receive terminal-related stop signals 
(SIGTSTP, SIGTTIN, SIGTTOU, but not SIGSTOP) must not be allowed to stop. 
The goal is to prevent stopped processes from languishing forever. (As SIGSTOP 
is sent only via kill(), it is assumed that the process or user sending a SIGSTOP 
can send a SIGCONT when desired.) Instead, the system must discard the stop 
signal. As an extension, it may also deliver another signal in its place. 4.3BSD 
sends a SIGKILL, which is effective, but probably too harsh, as SIGKILL is not 
catchable. Another possible choice is SIGHUP. 4.3BSD also does this for 
orphaned processes (processes whose parent has terminated) rather than 
members of orphaned process groups; this is less desirable because job control 
shells manage process groups. The standard also prevents SIGTTIN and 
SIGTTOU signals from being generated for processes in orphaned process groups 
as a direct result of activity on a terminal, preventing infinite loops when read() 
and write() calls generate signals that are discarded. (See Terminal Access 
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Control §B.7.1.1.4.) The Working Group considered a similar restriction on the 
generation of SIGTSTP, but that would be unnecessary and more difficult to 
implement due to its asynchronous nature. 

Although the standard requires that signal-catching functions be called with 
only one argument, there is nothing to prevent conforming implementations 
from extending the standard to pass additional arguments, as long as Strictly 
Conforming POSIX Applications continue to compile and execute correctly. Most 
traditional implementations do, in fact, pass additional, signal-specific argu- 
ments to certain signal-catching routines. 

There was a proposal to change the declared type of the signal handler to: 


void func (int sig, ... ); 


The usage of ellipses (“, ...”) is C Standard syntax to indicate a variable 
number of arguments. Its use was intended to allow the implementation to pass 
additional information to the signal handler in a standard manner. 

Unfortunately, this construct would require all signal handlers to be defined 
with this syntax, because the C Standard allows implementations to use a dif- 
ferent parameter passing mechanism for variable parameter lists than for non- 
variable parameter lists. Thus all existing signal handlers in all existing appli- 
cations would have to be changed to use the variable syntax in order to be stan- 
dard and to be portable. This is in conflict with the goal of Minimal Changes 
to Existing Application Code §B.1.2.9. 

When terminating a process from a signal-catching function, processes should 
be aware of any interpretation that their parent may make of the status 
returned by wait() or waitpid(). In particular, a signal-catching function should 
not call exit(0) or _exit(0) unless it wants to indicate successful termination. A 
non-zero argument to exit() or _exit() can be used to indicate unsuccessful ter- 
mination. Alternatively, the process can use ill() to send itself a fatal signal 
(first ensuring that the signal is set to the default action and not blocked). (See 
also _exit() §B.3.2.2). 

The behavior of unsafe functions, as defined by this section, is undefined 
when they are invoked from signal-catching functions in certain circumstances. 
The behavior of reentrant functions, as defined by this section, is as specified by 
the standard, regardless of invocation from a signal-catching function. This is 
the only intended meaning of the statement that reentrant functions may be 
used in signal-catching functions without restriction. Applications must still 
consider all effects of such functions on such things as data structures, files, and 
process state. In particular, application writers need to consider the restrictions 
on interactions when interrupting sleep() (see sleep() §3.4.8 and sleep() §B.3.4.3) 
and interactions among multiple handles for a file description (see Interac- 
tions of Other FILE-Type C Functions §8.2.3 and §B.8.2.3). The fact that 
any specific function is listed as reentrant does not necessarily mean that invo- 
cation of that function from a signal-catching function is recommended. 

In order to prevent errors arising from interrupting non-reentrant function 
calls, applications should protect calls to these functions either by blocking the 
appropriate signals or through the use of some programmatic semaphore. The 
standard does not address the more general problem of synchronizing access to 
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shared data structures. Note in particular that even the “safe” functions may 
modify the global variable errno; the signal-catching function may want to save 
and restore its value. Naturally, the same principles apply to the reentrancy of 
application routines and asynchronous data access. 

Note that longjmp() and siglongjmp() are not in the list of reentrant func- 
tions. This is because the code executing after the longjmp() or siglongjmp() 
can call any unsafe functions with the same danger as calling those unsafe func- 
tions directly from the signal handler. Applications that use longjmp() or 
siglongjmp() out of signal handlers require rigorous protection in order to be 
portable. Many of the other functions that are excluded from the list are tradi- 
tionally implemented using either the C language malloc() or free() functions or 
the C language standard I/O library, both of which traditionally use data struc- 
tures in a non-reentrant manner. Because any combination of different func- 
tions using a common data structure can cause reentrancy problems, the stan- 
dard does not define the behavior when any unsafe function is called in a signal 
handler that interrupts any unsafe function. 

B.3.3.1.4 Signal Effects on Other Functions. In the Trial Use Stan- 
dard the effect of signals interrupting functions was described under signals. 
Because of the various different cases, they are now described under each of the 
interruptible functions. 

The most common behavior of an interrupted function after a signal-catching 
function returns is for the interrupted function to give an [EINTR] error. How- 
ever, there are a number of specific exceptions, including sleep() and certain 
situations with read() and write(). 

The traditional implementations of many functions defined by this standard 
are not interruptible, but delay delivery of signals generated during their execu- 
tion until after they complete. This is never a problem for functions that are 
guaranteed to complete in a short (imperceptible to a human) period of time. It 
is normally those functions that can suspend a process indefinitely or for long 
periods of time (e.g. wait(), pause(), sigsuspend(), sleep(), or read()/write() on a 
slow device like a terminal) which are interruptible. This permits applications 
to respond to interactive signals or to set timeouts on calls to most such function 
with alarm(). Therefore implementations should generally make such functions 
(including ones defined as extensions) interruptible. 

Functions not mentioned explicitly as interruptible may be on some imple- 
mentations, possibly as an extension where the function gives an [EINTR] error. 
There are several functions (e.g. getpid(), getuid()) that are specified as never 
returning an error, which can thus never be extended in this way. 

B.3.3.2 Send a Signal to a Process. The semantics for permission 
checking for kill() differ between System V and most other implementations, 
such as Version 7 or 4.3BSD. The semantics chosen for the standard agree with 
System V. Specifically, a setuid process cannot protect itself against signals (or 
at least not against SIGKILL) unless it changes its real user ID. This choice 
allows the user who starts an application to send it signals even if it changes its 
effective user ID. The other semantics give more power to an application that 
wants to protect itself from the user who ran it. The statement that “the imple- 
mentation may still permit” a setuid application to receive such signals is 
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intended as a warning to application writers about this fact; the word may 
should be interpreted as describing a possible scenario, not as a specification of 
any optional semantics. 

Some implementations provide semantic extensions to the Aill() function 
when the absolute value of pid is greater than some maximum, or otherwise 
special, value. Negative values are a flag to Aill(). Since most implementations 
return [ESRCH] in this case, the Working Group felt that this behavior should 
not be standardized, although a conforming implementation could provide such 
an extension. 

The implementation-defined processes to which a signal cannot be sent may 
include the scheduler or init. 

Most existing implementations use kill (—1,sig) from a super-user process 
to send a signal to all processes (excluding system processes like init). This 
use of the ill() function is for administrative purposes only; portable applica- 
tions should not send signals to processes about which they have no knowledge. 
In addition, there are semantic variations among different implementations 
which, because of the limited use of this feature, were not necessary to resolve 
by standardization. System V implementations also use kill (-—1,sig) froma 
non-super-user process to send a signal to all processes with matching user IDs. 
This use was considered neither sufficiently widespread nor necessary for appli- 
cation portability to warrant inclusion in the standard. 

There was strong sentiment in the Working Group to specify that, if pid speci- 
fies that a signal be sent to the calling process and that signal is not blocked, 
that signal would be delivered before Aill() returns. This would permit a pro- 
cess to call kill() and be guaranteed that the call never return. However, tradi- 
tional implementations that provide only the signal() interface only make the 
weaker guarantee in the standard, because they only deliver one signal each 
time a process enters the kernel. Modifications to such implementations to sup- 
port the sigaction() interface generally require entry to the kernel following 
return from a signal-catching function, in order to restore the signal mask. 
Such modifications have the effect of satisfying the stronger requirement, at 
least when sigaction() is used, but not necessarily when signal() is used. The 
Working Group considered making the stronger requirement except when sig- 
nal() is used, but felt this would be unnecessarily complex. Implementors are 
encouraged to meet the stronger requirement whenever possible. In practice 
the weaker requirement is the same except in the rare case when two signals 
arrive during a very short window. This reasoning also applies to a similar 
requirement for sigprocmask() §3.3.5. 

In 4.2BSD, the SIGCONT signal can be sent to any descendant process regard- 
less of user ID security checks. This allows a job control shell to continue a job 
even if processes in the job have altered their user IDs (as in the su command). 
In keeping with the addition of the concept of sessions, similar functionality is 
provided by allowing the SIGCONT signal to be sent to any process in the same 
session regardless of user ID security checks. This is less restrictive than BSD 
in the sense that ancestor processes (in the same session) can now be the reci- 
pient. It is more restrictive than BSD in the sense that descendant processes 
which form new sessions are now subject to the user ID checks. A similar 
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relaxation of security is not necessary for the other job control signals since 
those signals are typically sent by the terminal driver in recognition of special 
characters being typed; the terminal driver bypasses all security checks. 

In secure implementations, a process may be restricted from sending a signal 
to a process having a different security label. In order to prevent the existence 
or non-existence of a process from being used as a covert channel, such 
processes should appear non-existent to the sender; i.e., [ESRCH] should be 
returned, rather than [EPERM], if pid refers only to such processes. 

Existing implementations vary on the result of a kill() with pid indicating an 
inactive process (a terminated process that has not been waited for by its 
parent). Some indicate success on such a call (subject to permission checking), 
while others give an error of [ESRCH]. Since this standard’s definition of process 
lifetime covers inactive processes, the [ESRCH] error as described is inappropri- 
ate in this case. In particular this means that an application cannot have a 
parent process check for termination of a particular child with kill() (usually 
this is done with the null signal); this can be done reliably with waitpid() 
Sor2a)) 

Various individuals have indicated that the name ill() is misleading, since 
the function is not always intended to cause process termination. However, the 
name is common to all traditional implementations, and any change would be in 
conflict with the goal of Minimal Changes to Existing Application Code 
§B.1.2.9. 

B.3.3.3 Manipulate Signal Sets. The implementation of the sigemp- 
tyset() (or sigfillset()) functions could quite trivially clear (or set) all the bits in 
the signal set. Alternatively, it would be reasonable to initialize part of the 
structure, such as a version field, to permit binary compatibility between 
releases where the size of the set varies. For such reasons, either sigemptyset() 
or sigfillset() must be called prior to any other use of the signal set, even if such 
use is read-only (e.g., as an argument to sigpending()). This function is not 
intended for dynamic allocation. 

The sigfillset() and sigemptyset() functions require that the resulting signal 
set include (or exclude) all the signals defined in this standard. Although it is 
outside the scope of this standard to place this requirement on signals that are 
implemented as extensions, it is recommended that implementation-defined sig- 
nals also be affected by these functions. However, there may be a good reason 
for a particular signal not to be affected. For example, blocking or ignoring an 
implementation-defined signal may have undesirable side effects whereas the 
default action for that signal is harmless. In such a case, it would be preferable 
for such a signal to be excluded from the signal set returned by sigfillset(). 

In earlier drafts of the standard there was no distinction between invalid and 
unsupported signals (the names of optional signals that were not supported by 
an implementation were not defined by that implementation). The [EINVAL] 
error was thus specified as a required error for invalid signals. With the dis- 
tinction, it does not make sense to require implementations of these functions to 
determine whether an optional signal is actually supported, as that could have a 
significant performance impact for little value. The error could have been 
required for invalid signals and optional for unsupported signals, but this 
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seemed unnecessarily complex. Thus the error is optional in both cases. 

B.3.3.4 Examine and Change Signal Action. Although the standard 
requires that signals that cannot be ignored shall not be added to the signal 
mask when a signal-catching function is entered, there is no explicit require- 
ment that subsequent calls to sigaction() reflect this in the information 
returned in the oact argument. In other words, if SIGKILL is included in the 
sa_mask field of act, it is unspecified whether or not a subsequent call to sigac- 
tion() will return with SIGKILL included in the sa_mask field of oact. 

The SA_NOCLDSTOP flag, when supplied in the act->sa_flags parameter, 
allows overloading SIGCHLD with the System V semantics that each SIGCLD 
signal indicates a single terminated child. Most portable applications that catch 
SIGCHLD are expected to install signal-catching functions that repeatedly call 
the waitpid() function with the WNOHANG flag set, acting on each child for 
which status is returned, until waitpid() returns zero. If stopped children are 
not of interest, the use of the SA_NOCLDSTOP flag can prevent the overhead of 
invoking the signal-catching routine when they stop. 

Some existing implementations also define other mechanisms for stopping 
processes, such as the ptrace() function. These implementations usually do not 
generate a SIGCHLD signal when processes stop due to this mechanism, how- 
ever that is beyond the scope of this standard. 

The standard requires that calls to sigaction() that supply a NULL aci argu- 
ment succeed, even in the case of signals that cannot be caught or ignored (1.e., 
SIGKILL or SIGSTOP). The System V signal() and BSD sigvec() functions return 
[EINVAL] in these cases and, in this respect, their behavior varies from sigac- 
tion(). 

The standard requires that sigaction() properly save and restore a signal 
action set up by the C Standard signa/() function. However, there is no guaran- 
tee that the reverse be true, nor could there be given the greater amount of 
information conveyed by the sigaction structure. Because of this, applications 
should avoid using both functions for the same signal in the same process. 
Since this cannot always be avoided in case of general-purpose library routines, 
they should always be implemented with sigaction(). 

It is the intention of the Working Group that signal() should be implement- 
able as a library routine using sigaction(). 

B.3.3.5 Examine and Change Blocked Signals. Note that when a 
process’s signal mask is changed in a signal-catching function that is installed 
by sigaction(), that the restoration of the signal mask on return from the 
signal-catching function overrides that change (see sigaction() §3.3.4). If the 
signal-catching function was installed with signal() it is unspecified whether 
this occurs. 

See Aill() §B.3.3.2 for a discussion of the requirement on delivery of signals. 

B.3.3.6 Examine Pending Signals. 

B.3.3.7 Wait for a Signal. Normally, at the beginning of a critical code 
section, a specified set of signals is blocked using the sigprocmask() function. 
When the process has completed the critical section and needs to wait for the 
previously blocked signal(s), it pauses by calling sigsuspend() with the mask 
that was returned by the sigprocmask() call. 
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B.3.4 Timer Operations. 

B.3.4.1 Schedule Alarm. Many traditional implementations (including 
Version 7 and System V) allow an alarm to occur up to a second early. Other 
implementations allow alarms up to half a second early, up to 1/{CLK_TCK} 
seconds early, or do not allow them to occur early at all. The latter is considered 
most appropriate, since it gives the most predictable behavior, especially since 
the signal can always be delayed for an indefinite amount of time due to 
scheduling. Applications can thus choose the seconds argument as the 
minimum amount of time they wish to have elapse before the signal. 

The term “real time” here and elsewhere (sleep (), times()) is intended to mean 
“wall clock” time as common English usage, and has nothing to do with “real- 
time operating systems.” It is in contrast to “virtual time,” which could be 
misinterpreted if just “time” were used. 

In some implementations, including 4.3BSD, very large values of the seconds 
argument are silently rounded down to an implementation-defined maximum 
value. This maximum is large enough (on the order of several months) that the 
effect is not noticeable. 

Application writers should note that the type of the argument seconds and the 
return value of alarm() is unsigned int. That means that a Strictly Conforming 
POSIX Application cannot pass a value greater than the minimum guaranteed 
value for {UINT_MAX}, which the C Standard sets as 65535, and any application 
passing a larger value is restricting its portability. The Working Group con- 
sidered using a different type, but existing implementations, including those 
with a 16-bit int type, consistently use either unsigned int or int. 

Application writers should be aware of possible interactions when the same 
process uses both the alarm() and sleep() functions (see sleep() §3.4.3 and 
§B.3.4.3). 

B.3.4.2. Suspend Process Execution. Many common uses of pause() 
have timing windows. The scenario involves checking a condition related to a 
signal and, if the signal has not occurred, calling pause(). When the signal 
occurs between the check and the call to pause(), the process often blocks inde- 
finitely. The sigprocmask() and sigsuspend() functions can be used to avoid this 
type of problem. 

B.3.4.3. Delay Process Execution. There are two general approaches to 
the implementation of the sleep() function. One is to use the alarm() function to 
schedule a SIGALRM signal and then suspend the process waiting for that sig- 
nal. The other is to implement an independent facility. The standard permits 
either approach. 

In order to comply with the wording of the introduction to Chapter 3, that no 
primitive shall change a process attribute unless explicitly described by the 
standard, an implementation using SIGALRM must carefully take into account 
any SIGALRM signal scheduled by previous alarm() calls, the action previously 
established for SIGALRM, and whether SIGALRM was blocked. If a SIGALRM 
has been scheduled before the sleep() would ordinarily complete, the sleep() 
must be shortened to that time, and a SIGALRM generated (possibly simulated 
by direct invocation of the signal-catching function) before sleep() returns. If a 
SIGALRM has been scheduled after the sleep() would ordinarily complete, it 
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must be rescheduled for the same time before sleep() returns. The action and 
blocking for SIGALRM must be saved and restored. 

Traditional implementations often implement the SIGALRM-based version 
using alarm() and pause(). One such implementation is prone to infinite hangs 
as described in pause() §B.3.4.2. Another such implementation uses the C 
language setjmp() and longjmp() functions to avoid that window. That imple- 
mentation introduces a different problem; when the SIGALRM signal interrupts 
a signal catching function installed by the user to catch a different signal the 
longjmp() aborts that signal-catching function. An implementation based on 
sigprocmask(), alarm(), and sigsuspend() can avoid these problems. 

Despite all reasonable care, there are several very subtle but detectable and 
unavoidable differences between the two types of implementation. These are 
the cases mentioned in the standard where some other activity relating to 
SIGALRM takes place, and the results are stated to be unspecified. All of these 
cases are sufficiently unusual as not to be of concern to most applications. 

(See also the discussion of the term “real time” in Schedule Alarm §B.3.4.1.) 

Because sleep() can be implemented using alarm(), the discussion about 
alarms occurring early under alarm() §B.3.4.1 apply to sleep() as well. 

Application writers should note that the type of the argument seconds and the 
return value of sleep() is unsigned int. That means that a Strictly Conforming 
POSIX Application cannot pass a value greater than the minimum guaranteed 
value for {UINT_MAX}, which the C Standard sets as 65535, and any application 
passing a larger value is restricting its portability. The Working Group con- 
sidered using a different type, but existing implementations, including those 
with a 16 bit int type, consistently use either unsigned int or int. 

Scheduling delays may cause the process to return from the sleep() function 
significantly after the requested time. In such cases, the return value should be 
set to zero, since the formula (requested time minus the time actually spent) 
yields a negative number and sleep() returns an unsigned int. 


B.4. Process Environment. 


B.4.1 Process Identification. 
B.4.1.1 Get Process and Parent Process IDs. 


B.4.2 User Identification. 

B.4.2.1 Get Real User, Effective User, Real Group, and Effective 
Group IDs. 

B.4.2.2 Set User and Group IDs. The saved set-user-ID capability 
allows a program to regain the effective user ID established at the last exec 
§3.1.2 call. Similarly, the saved set-group-ID capability allows a program to 
regain the effective group ID established at the last exec call. 

These two capabilities are derived from System V. Without them, a program 
may have to run as super-user in order to perform the same functions, because 
Super-user can write on the user’s files. This is a problem because such a pro- 
gram can write on any user’s files, and so must be carefully written to emulate 
the permissions of the calling process properly. 
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A process with appropriate privilege on a system with this saved ID capability 
establishes all relevant IDs to the new value since this function is used to estab- 
lish the identity of the user during login or su. Any change to this behavior 
would be dangerous since it involves programs that need to be trusted. 

The behavior of 4.2BSD and 4.3BSD that allows setting the real ID to the effec- 
tive ID is viewed as a value-dependent special case of appropriate privilege. 

B.4.2.3 Get Supplementary Group IDs. The related function set- 
groups() §B.4.2.3 is a privileged operation and therefore is not covered by this 
standard. 

The effective group ID may appear in the array returned by getgroups(), or it 
may be returned only by getegid(). This is a warning to programmers that 
duplication may exist, and that one needs to call getegid() to be sure of getting 
all of the information. Various implementation and administrative sequences 
(how did you get into these sets of groups, etc.) will cause these to vary. 

B.4.2.4 Get User Name. L_cuserid must be defined appropriately for a 
given implementation and must be greater than zero so that array declarations 
using it are accepted by the compiler. The value includes the terminating null 
byte. 


B.4.3. Process Groups. 

B.4.3.1 Get Process Group ID. 4.3BSD provides a getpgrp() function 
that returns the process group ID for a specified process. Although this function 
is used to support job control, all known job control shells always specify the cal- 
ling process with this function. Thus the simpler System V getpgrp() suffices 
and the added complexity of the 4.3BSD getpgrp() has been omitted from the 
standard. 

B.4.3.2 Create Session and Set Process Group ID. The setsid() func- 
tion is similar to the setpgrp() function of System V. System V, without job con- 
trol, groups processes into process groups and creates new process groups via 
setpgrp(); only one process group may be part of a login session. 

Job control allows multiple process groups within a login session. In order to 
limit job control actions so that they can only affect processes in the same login 
session, POSIX adds the concept of a session which is created via setsid(). The 
setsid() function also creates the initial process group contained in the session. 
Additional process groups can be created via the setpgid() function. A System V 
process group would correspond to a POSIX session containing a single POSIX 
process group. Note that this function requires that the calling process not be a 
process group leader. The usual way to ensure this is true is to create a new 
process with fork() and have it call setsid(). The fork() function guarantees that 
the process ID of the new process does not match any existing process group ID. 

B.4.3.3 Set Process Group ID for Job Control. The setpgid() function 
is used to group processes together for the purpose of signaling, placement in 
foreground or background, and other job control actions. See job control 
§B.2.3. 

The setpgid() function is similar to the setpgrp() function of 4.2BSD, except 
that 4.2BSD allowed the specified new process group to assume any value. This 
presents certain security problems and is more flexible than necessary to 
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support job control. 

To provide tighter security, setpgid() only allows the calling process to join a 
process group already in use inside its session or create a new process group 
whose process group ID was equal to its process ID. 

When a job control shell spawns a new job, the processes in the job must be 
placed into a new process group via setpgid(). There are two timing constraints 
involved in this action: 

(1) The new process must be placed in the new process group before the 
appropriate program is launched via one of the exec functions. 

(2) The new process must be placed in the new process group before the shell 
can correctly send signals to the new process group. 

To address these constraints, the following actions are performed: The new 
processes call setpgid() to alter their own process groups after fork() but before 
exec. This satisfies the first constraint. Under 4.3BSD, the second constraint is 
satisfied by the synchronization property of vfork(); that is, the shell is 
suspended until the child has completed the exec, thus ensuring that the child 
has completed the setpgid(). The Working Group considered adding a new ver- 
sion of fork() with this same synchronization property, but decided instead to 
merely allow the parent shell process to adjust the process group of its child 
processes via setpgid(). Both timing constraints are now satisfied by having 
both the parent shell and the child attempt to adjust the process group of the 
child process; it doesn’t matter which succeeds first. 

Because it would be confusing to an application to have its process group 
change after it began executing (i.e., after exec) and because the child process 
would already have adjusted its process group before this, the [EACCES] error 
was added to disallow this. 

One non-obvious use of setpgid() is to allow a job control shell to return itself 
to its original process group (the one in effect when the job control shell was exe- 
cuted). A job control shell does this before returning control back to its parent 
when it is terminating or suspending itself as a way of restoring its job control 
“state” back to what its parent would expect. (Note that the original process 
group of the job control shell typically matches the process group of its parent, 
but this is not necessarily always the case.) See also tcsetpgrp() §B.7.1.7. 


B.4.4 System Identification. 

B.4.4.1 System Name. The values of the structure members are not con- 
strained to have any relation to the version of this interface standard imple- 
mented in the operating system. An application implementor should instead 
depend on {_POSIX_VERSION} and related constants defined in Symbolic Con- 
stants §2.10. 

The standard does not define the sizes of the members of the structure and 
permits them to be of different sizes, although most implementations define 
them all to be the same size: eight bytes plus one byte for the string terminator. 
That size for nodename is not enough for use with many networks. 

The uname() function is specific to System III, System V, and related imple- 
mentations, and it does not exist in Version 7 or 4.3BSD. The values it returns 
are set at system compile time in those existing implementations. 
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4.3BSD has gethostname() and gethostid(), which return a symbolic name and 
a numeric value, respectively. There are related sethostname() and sethostid() 
functions that are used to set the values the other two functions return. The 
length of the host name is limited to 31 characters in most implementations and 
the host ID is a 32-bit integer. 


B.4.5 Time. The time() §4.5.1 function returns a value in seconds (type 
time_t) while times() §4.5.2 returns a set of values in {CLK_TCK}ths of a second 
(type clock_t). 

Some historical implementations, such as 4.3BSD, have mechanisms capable 
of returning more precise times (see gettimeofday() §B.4.5.1). A generalized 
timing scheme to unify these various timing mechanisms has been proposed but 
not adopted in this standard; see Realtime Extensions §A.2.5. 

B.4.5.1 Get System Time. Implementations in which time_t is a 32-bit 
signed integer (most historical implementations) will fail in the year 2038. The 
Working Group chose not to try to fix this. But they did require the use of 
time_t in order to ease the eventual fix. 

The use of the header <time.h> instead of <sys/types.h> allows compatibility 
with the C Standard. 

Many historical implementations (including Version’7) and the 1984 
/usr/group Standard use long instead of time_t. The present standard uses the 
latter type in order to agree with the C Standard. 

4.3BSD includes time() only as an interface to the more flexible gettimeofday() 
function. 

B.4.5.2 Process Times. The accuracy of the times reported is intention- 
ally left unspecified to allow implementations flexibility in design, from unipro- 
cessor to multiprocessor networks. 

The inclusion of times of child processes is recursive, so that a parent process 
may collect the total times of all of its descendants. But the times of a child are 
only added to those of its parent when its parent successfully waits on the child. 
Thus it is not guaranteed that a parent process will always be able to see the 
total times of all its descendants. 

(See also the discussion of the term “real time” in Schedule Alarm §B.3.4.1.) 

If the type clock_t is defined to be a signed 32-bit integer, it will overflow in 
somewhat more than a year if {CLK_TCK} is 60, or less than a year if it is 100. 
There are individual systems that run continuously for longer than that. The 
standard permits an implementation to make the reference point for the 
returned value be the startup time of the process, rather than system startup 
time. 

The term “charge” in this context has nothing to do with billing for services. 
The operating system accounts for time used in this way. That information 
must be correct, regardless of how that information is used. 
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B.4.6 Environment Variables. 

B.4.6.1 Environment Access. Additional functions putenv() and 
clearenv() were considered but rejected because they were considered to be more 
oriented towards system administration than ordinary application programs. 
This is being reconsidered for a supplement to this standard because uses from 
within an application have been identified since the decision was made. 

It was proposed that this function is properly part of Chapter 8. It is an 
extension to a function in Standard C. Because this function should be avail- 
able from any language, not just C, it appears here, to separate it from the 
material in Chapter 8 which is specific to the C binding. (The localization exten- 
sions to C are not, at this time, appropriate for other languages.) 


B.4.7 Terminal Identification. The difference between ctermid() and 
ttyname() is that ttyname() must be passed a file descriptor and returns the 
pathname of the terminal associated with that file descriptor, while ctermid() 
returns a string (such as /dev/tty) that will refer to the controlling terminal if 
used as a pathname. Thus ttyname() is useful only if the process already has at 
least one file open to a terminal. 

The historical value of ctermid() is /dev/tty; this is acceptable. The cter- 
mid() function should not be used to determine if a process actually has a con- 
trolling terminal, but merely the name that would be used. 

B.4.7.1 Generate Terminal Pathname. L_ctermid must be defined 
appropriately for a given implementation and must be greater than zero so that 
array declarations using it are accepted by the compiler. The value includes the 
terminating null byte. 

B.4.7.2, Determine Terminal Device Name. The term “terminal” is 
used instead of the historical term “terminal device” in order to avoid a refer- 
ence to an undefined term. 


B.4.8 Configurable System Variables. This section was added in 
response to requirements of application developers, and particularly the X/Open 
system vendors. It is closely related to Configurable Pathname Variables 
§$B.5.7 as well. 

Although a portable application can run on all systems by never demanding 
more resources than the minimum values published in the standard, it is useful 
for that application to be able to use the actual value for the quantity of a 
resource available on any given system. To do this, the application will make 
use of the value of a symbolic constant in <limits.h> or <unistd.h>. 

However, once compiled, the application must still be able to cope if the 
amount of resource available is increased. To that end, an application may need 
a means of determining the quantity of a resource, or the presence of an option, 
at execution time. 

Two examples are offered: 

(1) Applications may wish to act differently on systems with or without job 
control. Applications vendors who wish to distribute only a single binary 
package to all instances of a computer architecture would be forced to 
assume job control is never available if it were to rely solely on the 
<unistd.h> value published in the standard. 
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(2) International applications vendors occasionally require knowledge of the 
{CLK_TCK} value. Without the facilities of this section, they would be 
required to either distribute their applications partially in source form or to 
have 50 Hertz and 60 Hertz versions for the various countries they do busi- 
ness in. 

It is the understanding that many applications are actually distributed widely 
in executable form that lead to this facility. If limited to the most restrictive 
values in the headers, such applications would have to be prepared to accept the 
most limited environments offered by the smallest microcomputers. Although 
this is entirely portable, it was felt by the Working Group that they should be 
able to take advantage of the facilities offered by large systems, without the res- 
trictions associated with source and object distributions. 

During the very heated arguments that accompanied the discussions of this 
feature, it was pointed out that it is almost always possible for an application to 
discern what a value might be at run-time by suitably testing the waters. And, 
in any event, it could always be written to adequately deal with error returns 
from the various functions. In the end, it was felt that this imposed an unrea- 
sonable level of complication and sophistication on the application writer. 

This run-time facility is not meant to provide ever-changing values that appli- 
cations will have to check multiple times. The values are seen as changing no 
more frequently than once per system initialization, such as by a system 
administrator or operator with an automatic configuration program. The stan- 
dard specifies that they shall not change within the lifetime of the process. 

Some values apply to the system overall and others vary at the file system or 
directory level. These latter are described in Configurable Pathname Vari- 
ables §B.5.7. 

B.4.8.1 Get Configurable System Variables. Note that all values 
returned must be expressible as integers. The Working Group considered using 
string values, but the additional flexibility of this approach was rejected due to 
its added complexity of implementation and use. 

Some values, such as {PATH_MAX}, are sometimes so large that they must not 
be used to, say, allocate arrays. The sysconf() function will return a negative 
value to show that this symbolic constant isn’t even defined, in this case. 

{CLK_TCK} is not defined in languages other than C, so {_SC_CLK_TCK} is 
required for those languages. Because {CLK_TCK} has been in a state of change 
in the C Standard, there is a possibility of redundancy between that standard 
and POSIX because the number of ticks per second can be accessed both via 
{CLK_TCK} and via sysconf(). {CLK_TCK} is the preferred mechanism to access 
this value if it reflects the possibility of variation (as permitted by the 
C Standard at this writing). In fact, an attractive way to implement {CLK_TCK} 
is using sysconf(). To assure that there is at least one way to access the value, 
sysconf() continues to support access to the value. The specification assures 
that the redundancy won’t lead to different values. 
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B.5 Files and Directories. See pathname resolution §2.4. 

The wording regarding the group of a newly-created regular file, directory, or 
FIFO in open() §5.3.1, mkdir() §5.4.1, mkfifo() §5.4.2, respectively, defines the 
two acceptable behaviors in order to permit both the System V (and Version 7) 
behavior (in which the group of the new object is set to the effective group ID of 
the creating process) and the 4.3BSD behavior (in which the new object has the 
group of its parent directory). An application that needs a file to be created 
specifically in one or the other of the possible groups should use chown() §$5.6.5 
to ensure the new group regardless of the style of groups the interface imple- 
ments. Most applications will not and should not be concerned with the group 
ID of the file. 


B.5.1 Directories. Historical implementations prior to 4.2BSD had no spe- 
cial functions, types, or headers for directory access. Instead, directories were 
read with read() §6.4.1 and each program that did so had code to understand 
the internal format of directory files. Many such programs did not correctly 
handle the case of a maximum-length (historically fourteen character) filename 
and would neglect to add a null character string terminator when doing com- 
parisons. The access methods in the standard eliminate that bug, as well as 
hiding differences in implementations of directories or file systems. 

The directory access functions as described in an Appendix of the POSIX Trial 
Use Standard were derived from 4.2BSD, were adopted in System V Release 3 
and are in SVID Volume 3, with the exception of a type difference for the d_ino 
field. That field represents implementation-dependent or even file system- 
dependent information (the i-node number in most implementations). Since the 
directory access mechanism is intended to be implementation-independent, and 
since only system programs, not ordinary applications, need to know about the 
i-node number (or file serial number §2.3) in this context, the d_ino field does 
not appear in the present standard. Also, programs that want this information 
can get it with stat() §5.6.2. 

B.5.1.1 Format of Directory Entries. Information similar to that in the 
header <dirent.h> is contained in a file <sys/dir.h> in 4.2BSD and 4.3BSD. 
The equivalent in these implementations of struct dirent from the standard is 
struct direct. The filename was changed because the name <sys/dir.h> was 
also used in earlier implementations to refer to definitions related to the older 
access method; this produced name conflicts. The name of the structure was 
changed because the standard does not completely define what is in the struc- 
ture, so it could be different on some implementations from struct direct. 

The name of a character array of an unspecified size should not be used as an 
lvalue. Use of 


sezeoOr, (d name) 
is incorrect; use 
Setlen (d name) 


instead. 
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This description of the d_name element was changed because the previous 
version gave the impression that the character array d_name was of a fixed size. 
Implementations may need to declare struct dirent with an array size for 
d_name of 1, but the actual number of characters provided matches (or only 
slightly exceeds) the length of the file name. 

Currently, implementations are excluded if they have d_name with type 
char *. Lacking experience of such implementations, the Working Group 
declined to try to describe in standards language what to do if either type were 
permitted. 

B.5.1.2 Directory Operations. Based on historical implementations, 
the rules about file descriptors apply to directory streams as well. However, the 
standard does not mandate that the directory stream be implemented using file 
descriptors. Wording was added to the description of opendir() to clarify that if 
a file descriptor is used for the directory stream it is mandatory that closedir() 
deallocate the file descriptor. 

The returned value of readdir() merely represents a directory entry. No 
equivalence should be inferred. 

Since the structure and buffer allocation, if any, for directory operations are 
defined by the implementation, the standard imposes no portability require- 
ments for erroneous program constructs, erroneous data, or the use of indeter- 
minate values such as the use or referencing of a dirp value or a dirent struc- 
ture value after a directory stream has been closed or after a fork() or one of the 
exec function calls. 

Historical implementations of readdir() obtain multiple directory entries on a 
single read operation which permits subsequent readdir() operations to operate 
from the buffered information. Any wording which required each successful 
readdir() operation to mark the directory st_atime field for update would mili- 
tate against the historical performance-oriented implementations. 

Since readdir() returns NULL both: 

(1) when it detects an error, and; 

(2) when the end of the directory is encountered; 
an application that needs to tell the difference must set errno to zero before the 
call and check it if NULL is returned. Because the function must not change 
errno in case (2) and must set it to a non-zero value in case (1), zero errno after a 
call returning NULL indicates end of directory, otherwise an error. 

Routines to deal with this problem more directly were proposed: 


int derror (dirp) 
DIR *dirp; 

void clearderr (dirp) 
DIR «dirp; 


The first would indicate whether an error had occurred, and the second would 
clear the error indication. The simpler method involving errno was adopted 
instead by requiring that readdir() not change errno when end-of-directory is 
encountered. 
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Historical implementations include two more functions: 


long telldir (dirp) 
DIR *dirp; 


void seekdir (dirp, loc) 
DIR *dirp; 
long loc; 


The telldir() function returns the current location associated with the named 
directory stream. 

The seekdir() function sets the position of the next readdir() operation on the 
directory stream. The new position reverts to the one associated with the direc- 
tory stream when the ¢el/dir() operation was performed. 

These functions have restrictions on their use related to implementation 
details. Their capability can usually be accomplished by saving a filename 
found by readdir() and later using rewinddir() and a loop on readdir() to relo- 
cate the position from which the filename was saved. Though this method is 
probably slower than using seekdir() and telldir(), there are few applications in 
which the capability is needed. Furthermore, directory systems that are imple- 
mented using technology such as balanced trees where the order of presentation 
may vary from access to access do not lend themselves well to any concept along 
these lines. For these reasons, the Working Group decided not to include seek- 
dir() and tell/dir() in the standard. 

An error or signal indicating that a directory has changed while open was con- 
sidered but rejected. 


B.5.2 Working Directory. 

B.5.2.1 Change Current Working Directory. The chdir() function 
only affects the working directory of the current process. . 

The result if a NULL argument is passed to chdir() is left implementation- 

defined because some implementations dynamically allocate space in that case. 

B.5.2.2) Working Directory Pathname. Since the maximum pathname 
length is arbitrary unless {PATH_MAX} is defined, an application cannot supply 
a buf with size {{PATH_MAX} + 1} in general. 

Having the routine take no arguments and instead use the C function mal- 
loc() to produce space for the returned argument was considered. The advan- 
tage is that getcwd() knows how big the working directory pathname is and can 
allocate an appropriate amount of space. But the programmer would have to 
use the C function free() to free the resulting object, or each use of getcwd() 
would further reduce the available memory. Also, malloc() and free() are used 
nowhere else in the present standard. Finally, getcwd() is taken from the SVID, 
where it has the two arguments used in the standard. 

The older function getwd() was rejected for use in this context because it had 
only a buffer argument and no size argument, and thus had no way to prevent 
overwriting the buffer, except to depend on the programmer to provide a large 
enough buffer. 
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The result if a NULL argument is passed to getcwd() is left implementation- 
defined because some implementations dynamically allocate space in that case. 

If a program is operating in a directory where some (grand)parent directory 
does not permit reading, getcwd() may fail, as in most implementations it must 
read the directory to determine the name of the file. This can occur if search 
but not read permission is granted in an intermediate directory, or if the pro- 
gram is placed in that directory by some more privileged process (e.g. login). 
Including this error, [EACCESS], makes the reporting of the error consistent, 
and warns the application writer that getcwd() can fail for reasons beyond the 
control of the application writer or user. Some implementations can avoid this 
occurrence (e.g. by implementing getcwd() using pwd, where pwd is a set-user- 
root process), thus the error was made optional. 

Because the standard permits the addition of other errors, this would be a 
common addition and yet one that applications could not be expected to deal 
with without this addition. 

Some current implementations use {PATH_MAX}+2 bytes. These will have to 
be changed. Many of those same implementations also may not diagnose the 
[ERANGE] error properly anyway or deal with a common bug having to do with 
newline in a directory name (the fix to which is essentially the same as the fix 
for using +1 bytes), so this is not a severe hardship. 


B.5.3. General File Creation. Because there is no portable way to specify 
a value for the argument indicating the file mode bits (except zero), 
<sys/stat.h> is included with the functions that reference mode bits. 

B.5.3.1 Open a File. Except as specified in the standard, the flags 
allowed in oflag are not mutually exclusive and any number of them may be 
used simultaneously. 

Some implementations permit opening FIFOs with O_RDWR. Since FIFOs 
could be implemented in other ways, and since two file descriptors can be used 
to the same effect, this possibility is left as undefined. 

See getgroups() §B.4.2.3 about the group of a newly-created file. 

The use of open() §5.3.1 to create a regular file is preferable to the use of 
creat() §5.3.2 because the latter is redundant and included only for historical 
reasons. 

The use of the O_TRUNC flag on FIFOs and directories (pipes cannot be 
open()-ed) must be permissible without unexpected side-effects (e.g., creat() on a 
FIFO must not remove data). Other file types, particularly implementation- 
defined ones, are left implementation-defined. 

Implementations may deny access and return [EACCES] for reasons other 
than just those listed in the [EACCES] definition. 

The O_NOCTTY flag was added to allow applications to avoid unintentionally 
acquiring a controlling terminal as a side-effect of opening a terminal file. The 
standard does not specify how a controlling terminal is acquired, but it allows 
an implementation to provide this on open() if the O_NOCTTY flag is not set and 
other conditions specified in The Controlling Terminal §7.1.1.3 are met. The 
O_NOCTTY flag is an effective no-op if the file being opened is not a terminal 
device. 
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In historical implementations the value of O_RDONLY is zero. Because of that 
it is not possible to detect the presence of O_RDONLY and another option. 
Future implementations and revisions would be wise to encode O_RDONLY and 
O_WRONLY as bit flags so that: 


O_RDONLY | O_WRONLY == O_RDWR 


See the rationale for the change from O_NDELAY to O_NONBLOCK in Input 
and Output Primitives §B.6. 

B.5.3.2 Create a New File or Rewrite an Existing One. The creat() 
function is redundant. Its services are also provided by the open() function. It 
has been included primarily for historical purposes since many existing applica- 
tions depend on it. It is best considered a part of the C binding rather than a 
function that should be provided in other languages. 

B.5.3.3 Set File Creation Mask. Unsigned argument and return types 
for umask() were proposed. The return type and the argument were both 
changed to mode_t §B.2.6. 

Historical implementations have made use of additional bits in cmask for 
their implementation-specific purposes. The addition of the text that the mean- 
ing of other bits of the field are implementation-defined permits these imple- 
mentations to conform to the standard. 

B.5.3.4 Link to a File. See directory entry §B.2.3. 

Linking to a directory is restricted to the super-user in most historical imple- 
mentations because this capability may produce loops in the file hierarchy or 
otherwise corrupt the file system. This standard continues that philosophy by 
prohibiting link() and unlink() from doing this. Other functions could do it if 
the implementor designed such an extension. 

Some historical implementations allow linking of files on different file sys- 
tems. Wording was added to explicitly allow this optional behavior. 


B.5.4 Special File Creation. 

B.5.4.1 Make a Directory. See mode_t §B.2.6. 

The mkdir() function originated in 4.2BSD and was added to System V in 
Release 3.0, following the Trial Use Standard. 

4.3BSD detects [ENAMETOOLONG]. 

See getgroups() §B.4.2.3 about the group of a newly-created directory. 

B.5.4.2 Make a FIFO Special File. The syntax of this routine is 
intended to maintain compatibility with existing implementations of mknod(). 
The latter function was included in the 1984 /usr/group Standard, but only for 
use in creating FIFO special files. The mknod() function was excluded from 
POSIX as implementation-defined and replaced by mkdir() §5.4.1 and mkfifo() 
85.4.2. 

See getgroups §B.4.2.3 about the group of a newly-created FIFO. 


B.5.5 File Removal. The rmdir() and rename() functions originated in 
4.2BSD and they used [ENOTEMPTY] for the condition when the directory to be 
removed does not exist or new already exists. When the 1984 /usr/group Stan- 
dard was published, it contained [EEXIST] instead. When AT&T adopted these 
functions into System V, they used the /usr/group Standard as their reference. 
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Therefore, several existing applications and implementations support/use both 
forms and the Working Group could not agree on either value. All implementa- 
tions are required to supply both [EEXIST] and [ENOTEMPTY] in <errno.h> 
with distinct values so that applications can use both values in C language 
case statements. 

When this function was added to System V (in Release 3.0) it used [ENOENT] 
where the standard uses [ENAMETOOLONG]. Volume 3 of the SVID, page 129, 
states: “FUTURE DIRECTION: To conform with the IEEE POSIX standard, when 
it is adopted as a full-use standard, the value of errno indicating that ...” 

B.5.5.1 Remove Directory Entries. Unlinking a directory is restricted 
to the super-user in many historical implementations for reasons given in link() 
§B.5.3.4. But see rename() §B.5.5.3. 

The meaning of [EBUSY] in traditional implementations is “mount point 
busy.” Since this standard does not cover the system administration concepts of 
mounting and unmounting, the description of the error was changed to 
“resource busy.” (This meaning is used by some device drivers when a second 
process tries to open an exclusive use device.) The wording is also intended to 
allow implementations to refuse to remove a directory if it is the root or current 
working directory of any process. 

B.5.5.2 Remove a Directory. See also File Removal §B.5.5 and 
[EBUSY] §B.5.5.1. 

B.5.5.38 Rename a File. This rename() function is equivalent for regular 
files to that defined by the C Standard. Its inclusion here expands that defini- 
tion to include actions on directories and specifies behavior when the new 
parameter names a file that already exists. That specification requires that the 
action of the function be atomic. 

One of the reasons for introducing this function was to have a means of 
renaming directories while permitting implementations to prohibit the use of 
link() §5.3.4 and unlink() §5.5.1 with directories, thus constraining links to 
directories to those made by mkdir() §5.4.1. 

The specification that if old and new refer to the same file describes existing, 
although undocumented, 4.3BSD behavior. It is intended to guarantee that:. 


rFenamedk" x" pees 


does not remove the file. 

Renaming dot or dot-dot is prohibited in order to prevent cyclical file system 
paths. 

See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in File 
Removal §B.5.5 and [EBUSY] in Remove Directory Entries §B.5.5.1. 


B.5.6 File Characteristics. The function ustat(), which appeared in the 
1984 /usr/group Standard and is still in the SVID, was removed from the 
present standard before Trial Use because it was: 

(1) Not reliable. The amount of space available can change between the time 
the call is made and the time the calling process attempts to use it. 
(2) Not required. The only known program that uses it is the text editor ed. 
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It was also not readily extensible to networked systems. 

B.5.6.1 File Characteristics: Header and Data Structure. See Prim- 
itive System Data Types §B.2.6. 

A conforming C language application must include <sys/stat.h> for functions 
that have arguments or return values of type mode_t, so that symbolic values 
for that type can be used. An alternative would be to require that these con- 
stants are also defined by including <sys/types.h>. 

The S_ISUID and S_ISGID bits may be cleared on any write, not just on open() 
$5.3.1, as some historical implementations do it. 

System calls that update the time entry fields in the stat structure must be 
documented by the implementors. POSIX conforming systems should not update 
the time entry fields for functions listed in the standard unless the standard 
requires that they do, except in the case of documented extensions to the stan- 
dard. 

Note that st_dev must be unique within a Local Area Network (LAN) in a “sys- 
tem” made up of multiple computers’ file systems connected by a LAN. 

Networked implementations of a POSIX system must guarantee that all files 
visible within the file tree (including parts of the tree that may be remotely 
mounted from other machines on the network) on each individual processor are 
uniquely identified by the combination of the st_ino and st_dev fields. 

B.5.6.2 Get File Status. The intent of the paragraph describing “addi- 
tional or alternate file access contro] mechanisms” is to allow a secure imple- 
mentation where a process with a label that does not dominate the file’s label 
cannot perform a stat() function. This is not related to read permission; a pro- 
cess with a label that dominates the file’s label will not need read permission. 
An implementation that supports write-up operations could fail fstat() function 
calls even though it has a valid file descriptor open for writing. 

B.5.6.3 File Accessibility. Some Working Group discussions centered 
around inadequacies in the access() function led to the creation of an eaccess() 
function because: 

(1) Historical implementations of access() don’t test file access correctly 
when the process’s real user ID is super-user. In particular, they always 
return zero when testing execute permissions without regard to whether the 
file is executable. 

(2) The super-user has complete access to all files on a system. As a conse- 
quence, programs started by the super-user and switched to the effective 
user ID with lesser privileges cannot use access() to test their file access per- 
missions. 

After eaccess() was reviewed, the Working Group found that it still didn’t 
resolve problem (1), so the standard now allows access() to behave in the desired 
way because several implementations have corrected the problem. It was also 
argued that problem (2) is more easily solved by using open(), chdir(), or one of 
the exec functions as appropriate and responding to the error there, rather than 
creating a new function that wouldn't be as reliable. Therefore, eaccess() was 
taken back out of the standard. 

Secure implementations will probably need an extended access()-like func- 
tion, but the Working Group did not have enough of the requirements to define 
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it yet. This could be proposed as an extension to the Full Use Standard. See 
Trusted System Extensions §A.2.7. 

The sentence concerning appropriate privileges and execute permission bits 
reflects the two possibilities implemented by historical implementations when 
checking super-user access for X_OK. 

B.5.6.4 Change File Modes. The standard specifies that the S_ISGID bit 
is cleared by chmod() on a regular file under certain conditions. This is speci- 
fied on the assumption that regular files may be executed and the system should 
prevent users from making executable setgid files perform with privileges that 
the caller doesn’t have. On implementations that support execution of other file 
types, the S_ISGID bit should be cleared for those file types under the same cir- 
cumstances. 

Implementations which use the S_ISUID bit to indicate some other function 
(for example, mandatory record locking) on non-executable files need not clear 
this bit on writing. They should clear the bit for executable files and any other 
cases where the bit grants special powers to processes that change the file con- 
tents. Similar comments apply to the S_ISGID bit. 

B.5.6.5 Change Owner and Group of File. System III and System V 
allow a user to give away files, that is, the owner of a file may change its user ID 
to anything. This is a serious problem for implementations which are intended 
to meet government security regulations. Version 7 and 4.3BSD permit only the 
super-user to change the user ID of a file. Some government agencies (usually 
not ones concerned directly with security) find this limitation too confining. The 
standard uses “may” to permit secure implementations while not disallowing 
System V. : 

System III and System V allow the owner of a file to change the group ID to 
anything. Version 7 permits only the super-user to change the group ID of a file. 
4.3BSD permits the owner to change the group ID of a file to its effective group 
ID or to any of the groups in the list of supplementary group IDs, but to no oth- 
ers. 

Although chown() can be used on some systems by the file owner to change 
the owner and group to any desired values, the only portable use of this function 
is to change the group of a file to the effective GID of the calling process or to a 
member of its group set. 

The decision to require that, for non-privileged processes, the S_ISUID and 
S_ISGID bits be cleared on regular files but only may be cleared on non-regular 
files was to allow plans for using these bits in implementation-specified 
manners on directories. Similar cases could be made for other file types, so the 
standard does not require that these bits be cleared except on regular files. 
Note that as these cases arise, the system implementors will have to determine 
whether these features enable any security loopholes and specify appropriate 
restrictions. If the implementation supports executing any file types other than 
regular files, the S_ISUID and S_ISGID bits should be cleared for those file types 
in the same way as they are on regular files. 
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B.5.6.6 Set File Access and Modification Times. The actime struc- 
ture member must be present, so that an application may set it, even though an 
implementation may ignore it and not change the access time on the file. If an 
application intends to leave one of the times of a file unchanged while changing 
the other, it should use stat() §5.6.2 to retrieve the file’s st_atime and st_mtime 
§5.6.1.3 parameters, set actime and modtime in the buffer, and change one of 
them before making the wtime() call. 


B.5.7 Configurable Pathname Variables. When the run-time facility 
described in Configurable System Variables §B.4.8 was designed, it was 
realized that some variables change depending on the file system. For example, 
it is quite feasible for a system to have two varieties of file systems mounted: a 
System V, and; a Berkeley “Fast File System.” 

If limited to strictly compile-time features, no application that was widely dis- 
tributed in executable binary form could rely on more than 14 bytes in a path- 
name component, as that is the minimum published for {NAME_MAX} in this 
standard. The pathconf() function allows the application to take advantage of 
the most liberal file system available at run-time. In many Berkeley-based sys- 
tems, 255 bytes are allowed for pathname components. 

These values are potentially changeable at the directory level, not just at the 
file system. And, unlike the overall system variables, there is no guarantee that 
these might not change during program execution. 

B.5.7.1 Get Configurable Pathname Variables. The pathconf() func- 
tion was proposed immediately after the sysconf() function when it was realized 
that some configurable values may differ across file system, directory, or device 
boundaries. 

For example, {NAME_MAX} frequently changes between System V and BSD- 
based file systems; System V uses a maximum of 14, Berkeley 255. On an 
implementation that provided both types of file systems, an application would 
be forced to limit all pathname components to 14 bytes, as this would be the 
value specified in <limits.h> on such a system. 

Therefore, various useful values can be queried on any pathname or file 
descriptor, assuming that the appropriate permissions are in place. 

The value returned for the variable {PATH_MAX} indicates the longest relative 
pathname that could be given if the specified directory is the process’s current 
working directory. A process may not always be able to generate a name that 
long and be able to use it if a subdirectory in the pathname crosses into a more 
restrictive file system. 

The value returned for the variable {,.POSIX_CHOWN_RESTRICTED} also 
applies to directories that are not mounted on. The value may change when 
crossing a mount point, so applications that need to know-should check for each 
directory. (Note that an even easier check is to try the chown() function and 
look for an error in case it happens.) 

Unlike the values returned by sysconf(), the pathname-oriented variables are 
potentially more volatile and are not guaranteed to remain constant throughout 
the process’s lifetime. For example, in between two calls to pathconf() the file 
system in question may have been unmounted and remounted with different 
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characteristics. 

Also note that most of the errors are optional. If one of the variables always 
has the same value on an implementation, the implementation need not look at 
path or fildes to return that value and is, therefore, not required to detect any of 
the errors except the meaning of [EINVAL] that indicates that the value of name 
is not valid for that variable. 

If the value of any of the limits described in Run-Time Invariant Values 
(Possibly Indeterminate) §2.9.4 or Pathname Variable Values §2.9.5 are 
indeterminate (logically infinite), they will not be defined in <limits.h> and the 
pathconf() and fpathconf() functions will return -1 without changing errno. 
This can be distinguished from the case of giving an unrecognized name argu- 
ment because errno will be set to [EINVAL] in this case. 

Since —1 is a valid return value for the pathconf() and fpathconf() functions, 
applications should set errno to zero before calling them and check errno only if 
the return value is —1. 


B.6 Input and Output Primitives. Rationale for the Change from 
O_NDELAY to O_NONBLOCK. 

System III and System V have included a flag, O_NDELAY, to mark file 
descriptors so that user processes would not block when doing I/O to them. If 
the flag is set, a read() §6.4.1 or write() §6.4.2 call which would otherwise need 
to block for data returns a value of zero instead. But a read() call also returns a 
value of zero on end-of-file, and applications have no way to distinguish between 
these two conditions. 

BSD systems support a similar feature through a flag with the same name, 
but somewhat different semantics. The flag applies to all users of a file (or 
socket) rather than only to those sharing a file descriptor. The BSD interface 
provides a solution to the problem of distinguishing between a blocking condi- 
tion and an end-of-file condition by returning an error, [EWOULDBLOCK], on a 
blocking condition. 

The 1984 /usr/group Standard includes an interface with some features from 
both AT&T and BSD. The overall semantics are that it applies only to a file 
descriptor. However, the return indication for a blocking condition is an error, 
[EAGAIN]. This was the starting point for POSIX. 

The problem with the 1984 /usr/group Standard is that it does not allow 
compatibility with existing applications. An implementation cannot both con- 
form to this standard and support applications written for existing AT&T or BSD 
systems. This was the cause of at least one objection during the trial-use ballot- 
ing. Several changes have been considered, either at that time or more recently, 
to address this issue. These include: 

(1) No change (from 1984 /usr/group Standard); 

(2) Changing to System III/V semantics; 

(3) Changing to BSD semantics; 

(4) Broadening the standard to allow conforming implementation a choice 
among these semantics; 

(5) Changing the name of the flag from O_NDELAY; 

(6) Changing to System III/V semantics and providing a new call to 
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distinguish between blocking and end-of-file conditions. 

The consensus of the Working Group was that (5) is the best alternative. The 
new name is O_NONBLOCK. This alternative allows a conforming implementa- 
tion to provide backward compatibility at the source and/or object level with 
either AT&T or BSD systems (but the standard does not require or even suggest 
that this be done). It also allows a Conforming POSIX Application Using Exten- 
sions the functionality to distinguish between blocking and end-of-file condi- 
tions, and to do so in as simple a manner as any of the alternatives. The 
greatest shortcoming was that it forces all existing AT&T and BSD applications 
that use this facility to be modified in order to strictly conform to the standard. 
This same shortcoming applies to (1) and (4) as well, and it applies to one group 
of applications for (2), (3), and (6). 

Systems may choose to implement both O_LNDELAY and O_NONBLOCK, and 
there is no conflict as long as an application does not turn both flags on at the 
same time. 

See also the discussion of scope in Data Definitions for File Control 
Operations §B.5.6.1. 


B.6.1 Pipes. An implementation that fails write() operations on fildes[0] or 
read()s on fildes[1] is not required. Historical implementations (Version 7 and 
System V) return the error [EBADF] in such cases. This allows implementations 
to set up a second pipe for full duplex operation at the same time. A conforming 
application that uses the pipe() function as described in this standard will 
succeed whether this second pipe is present or not. 

B.6.1.1 Create an Inter-Process Channel. The wording carefully 
avoids using the verb “to open” in order to avoid any implication of use of open() 
85.3.1. 

See also Write to a Pipe §B.6.4.2. 


B.6.2 File Descriptor Manipulation. 

B.6.2.1 Duplicate an Open File Descriptor. The dup() and dup2() 
functions are redundant. Their services are also provided by the fen#l() func- 
tion. They have been included in this standard primarily for historical reasons, 
since many existing applications use them. 

The dup2() function is not intended for use in critical regions as a synchroni- 
zation mechanism. 

In the description of [EBADF] the case of fildes being out of range is covered 
by the given case of fildes not being valid. The descriptions for fildes and fildes2 
are different because the only kind of invalidity that is relevant for fildes2 is 
whether it is out of range, that is, it does not matter whether fildes2 refers to an 
open file when the dup2() call is made. 

If fildes2 is a valid file descriptor, it shall be closed, regardless of whether the 
function returns an indication of success or failure, unless fildes2 is equal to 


fildes. 
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B.6.3 File Descriptor Deassignment. 
B.6.3.1 Close a File. Once a file is closed, the file descriptor no longer 
exists, since the integer corresponding to it no longer refers to a file. 
The use of interruptible device close routines should be discouraged to avoid 
problems with the implicit closes of file descriptors by exec and exit(). The stan- 
dard only intends to permit such behavior by specifying the [EINTR] error case. 


B.6.4 Input and Output. Whether the return values of, and nbyte argu- 
ments to, read() §6.4.1 and write() §6.4.2 should be signed or unsigned was a 
chronic source of controversy. On machines where type int is of sixteen bits, 
only 32767 bytes may be transferred on one function call. If nbyte were 
unsigned, it would be convenient for the return value to be of the same type. 
But if the returned value were unsigned, it would be necessary to compare it to 
((unsigned )—1) in order to detect an error. Although a definition such as IO_ERR 
could be provided to simplify code, still many existing applications would not 
conform. 

The Working Group decided to make nbyte unsigned, with the results of use of 
values greater than {INT_MAX} (often 32767) being made implementation- 
defined. However, the return value was left signed to avoid the error-detection 
problem. It is still possible to compare the return value directly with nbyte, 
since the C Standard specifies that the comparison will be done unsigned. 

Use of the type long was considered in order to avoid the sixteen bit problem, 
but not adopted. 

New functions like read() and write() called lread() and lwrite() and differing 
only in that their nbyte argument and return values would be of type off_t §2.6 
were proposed but rejected. The Working Group is not necessarily against the 
creation of /read() and lwrite() calls, but was unable to clearly identify the need 
given the above. It was also noted that C has similar constraints parallel to 
those mentioned above, and that the type of sizeof is not necessarily long (where 
the largest object cannot exceed sizeof (char[INT MAX]). 

The standard requires that no action be taken when nbyte is zero. This is not 
intended to take precedence over detection of errors (such as bad buffer pointers 
or file descriptors). This is consistent with the rest of the standard, but the 
phrasing here could be misread to require detection of the zero case before any 
other errors. A value of zero is to be considered a correct value, for which the 
semantics are a no-op. 

There were recommendations to add format parameters to read() and write() 
in order to handle networked transfers among heterogeneous file system and 
base hardware types. Such a facility may be required for support by the OSI 
presentation of layer services. However, the Working Group determined that 
this should correspond with similar C Language facilities, and that is beyond 
the scope of the 1003.1 effort. The concept was suggested to X3J11 for their con- 
sideration as a possible area for future work. 

In 4.3BSD, a read() or write() that is interrupted by a signal before transfer- 
ring any data does not by default return an [EINTR] error, but is restarted. In 
4.2BSD, 4.3BSD, and the Eighth Edition there is an additional function, select (), 
whose purpose is to pause until specified activity (data to read, space to write, 
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etc.) is detected on specified file descriptors. It is common in applications writ- 
ten for those systems for select() to be used before read() in situations (such as 
keyboard input) where interruption of I/O due to a signal is desired. But this 
approach does not conform, because select() is not in the standard. 4.3BSD 
semantics can be provided by extensions to this standard. 

The standard permits read() and write() to return the number of bytes suc- 
cessfully transferred when interrupted by an error. This is not simply required 
because it was not done by Version 7, System III, or System V, and because 
some hardware may not be capable of returning information about partial 
transfers if a device operation is interrupted. This unhappily does make writing 
a Conforming POSIX Application more difficult in circumstances where this 
could occur. 

Requiring this behavior does not address the situation of pipelined buffers, 
such as might be found in streaming tape drives or other devices that read 
ahead of the actual requests. The signal interruption will often indicate an 
exceptional condition and flush all buffers. Thus the amount read from the dev- 
ice may be different from the amount transferred to the application. 

The issue of which files or file types are interruptible is considered an imple- 
mentation design issue. This is often affected primarily by hardware and relia- 
bility issues. 

B.6.4.1 Read from a File. The standard does not specify the value of the 
file offset after an error is returned; there are too many cases. For program- 
ming errors, such as [EBADF], the concept is meaningless since no file is 
involved. For errors that are detected immediately, such as [EAGAIN], clearly 
the pointer should not change. After an interrupt or hardware error, however, 
an updated value would be very useful and is the behavior of many implementa- 
tions. 

References to actions taken on an “unrecoverable error” have been removed. 
It is considered beyond the scope of this standard to describe what happens in 
the case of hardware errors. 

B.6.4.2 Write to a File. An attempt to write to a pipe or FIFO has 
several major characteristics: 

Atomic/non-atomic 
A write is atomic if the whole amount written in one operation is not 
interleaved with data from any other process. This is useful when 
there are multiple writers sending data to a single reader. Applications 
need to know how large a write request can be expected to be per- 
formed atomically. This maximum is called {PIPE_BUF}. The standard 
does not say whether write requests for more than {PIPE_BUF} bytes 
will be atomic, but requires that writes of {PIPE_BUF} or less bytes shall 
be atomic. 

Blocking/immediate 
Blocking is only possible with O_NONBLOCK clear. If there is enough 
space for all the data requested to be written immediately, the imple- 
mentation should do so. Otherwise, the process may block, that is, 
pause until enough space is available for writing. The effective size of a 
pipe or FIFO (the maximum amount that can be written in one 
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operation without blocking) may vary dynamically, depending on the 

implementation, so it is not possible to specify a fixed value for it. 
Complete/partial/deferred 

A write request, 


int fildes, nbyte, ret; 
char *buf; 


ret = write (fildes, buf, nbyte); 


may return 

complete: ret = nbyte 

partial: ret <nbyte 
This shall never happen if nbyte < {PIPE_BUF}. If it does 
happen (with nbyte > {PIPE_BUF}), the standard does not 
guarantee atomicity, even if ret < {PIPE_BUF}, because 
atomicity is guaranteed according to the amount 
requested , not the amount written. 

deferred: ret =—1, errno = [EAGAIN] 
This error indicates that a later request may succeed. It 
does not indicate that it shall succeed, even if nbyte < 
{PIPE_BUF}, because if no process reads from the pipe or 
FIFO, the write will never succeed. An application could 
usefully count the number of times [EAGAIN] is caused by 
a particular value of nbyte > {PIPE_BUF} and perhaps do 
later writes with a smaller value, on the assumption that 
the effective size of the pipe may have decreased. 

Partial and deferred writes are only possible with O_NONBLOCK set. 
The relations of these properties are best shown in tables. 


| Write to a Pipe or FIFO with O_NONBLOCK clear 
immediately 
writable: | none some nbyte 


atomic atomic atomic 
nbyte < blocking blocking immediate 
{PIPE_BUF} nbyte nbyte nbyte 


| nbyte > blocking blocking blocking 
{PIPE_BUF} nbyte nbyte nbyte 


If the O_NONBLOCK flag is clear, a write request shall block if the amount 
writable immediately is less than that requested. If the flag is set (by fentl()), a 
write request shall never block. 

The Working Group decided not to make an exception regarding partial writes 
when O_NONBLOCK is set. With the exception of writing to an empty pipe, the 
standard does not specify exactly when a partial write will be performed since 
that would require specifying internal details of the implementation. Every 
application should be prepared to handle partial writes when O_NONBLOCK is 
set and the requested amount is greater than {PIPE_BUF}, just as every 
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Write to a Pipe or FIFO with O_NONBLOCK set 


immediately 
writable: none some nbyte 


nbyte < —1, —1, atomic 
{PIPE_BUF} [EAGAIN] [EAGAIN] nbyte 
< nbyte < nbyte 


—l, or —l, or —1, 
[EAGAIN] [EAGAIN]  [EAGAIN] 


nbyte > 
{PIPE_BUF} 


application should be prepared to handle partial writes on other kinds of file 
descriptors. 

Where the standard requires —1 returned and errno set to [EAGAIN], most his- 
torical implementations return zero (with the O_NDELAY flag set: that flag is 
the historical predecessor of O_.NONBLOCK, but is not itself in the standard). 
The error indications in the standard were chosen so that an application can 
distinguish these cases from end-of-file. While write() cannot receive an indica- 
tion of end-of-file, read() can, and the Working Group chose to make the two 
functions have similar return values. Also, some existing systems (e.g., Eighth 
Edition) permit a write of zero bytes to mean that the reader should get an end- 
of-file indication: for those systems, a return value of zero from write() indicates 
a successful write of an end-of-file indication. 

The concept of a {PIPE_MAX} limit (indicating the maximum number of bytes 
that can be written to a pipe in a single operation) was discussed by the Work- 
ing Group. The Group decided this concept would unnecessarily limit applica- 
tion writing. 

See also the discussion of O_NONBLOCK in Input and Output Primitives 
§B.6. 

The standard does not specify the value of the file offset after an error is 
returned, there are too many cases. For programming errors, such as [EBADF], 
the concept is meaningless since no file is involved. For errors that are detected 
immediately, such as [EAGAIN], clearly the pointer should not change. After an 
interrupt or hardware error, however, an updated value would be very useful 
and is the behavior of many implementations. 

The standard does not specify behavior of concurrent writes to a file from 
multiple processes. Applications should use some form of concurrency control. 

References to actions taken on an “unrecoverable error” have been removed. 
It is considered beyond the scope of this standard to describe what happens in 
the case of hardware errors. 


B.6.5 Control Operations on Files. 

B.6.5.1 Data Definitions for File Control Operations. The main dis- 
tinction between the file descriptor flags and the file status flags is scope. The 
former apply to a single file descriptor only, while the latter apply to all file 
descriptors that share a common open file description (by inheritance through 
fork() §3.1.1 or an F_FDUPFD operation with fentl() §6.5.2). For O_NONBLOCK, 
this scoping is like that of O_.NDELAY in System V rather than in 4.3BSD, where 
the scoping for O_NDELAY is different from all the other flags accessed via the 


B.6 Input and Output Primitives. 255 


IEEE 
Std 1003.1-1988 IEEE STANDARD PORTABLE OPERATING SYSTEM 


same commands. 
For example: 


fdl — open, (pathname, cf lags, 
fd2 enbyo. (necclla) a 
£d3— Open (pathname, OLlagan, 


Does an fentl() call on fd1 also apply to fd2 or fd3 or to both? According to the 
standard, F_SETFD applies only to fd1, while F_LSETFL applies to fdl and fd2 but 
not to fd3. This is in agreement with all common historical implementations 
except for BSD with the F_SETFL command and the O_NDELAY flag (which 
would apply to fd3 as well). Note that this does not force any incompatibilities 
in BSD implementations, because O_NDELAY is not in the standard. See also 
O_NONBLOCK §B.6. 

B.6.5.2 File Control. The ellipsis in the Synopsis is the syntax specified 
by the C Standard for a variable number of arguments. It is used because 
System V uses pointers for the implementation of file locking functions. 

POSIX permits concurrent read and write access to file data using the fentl() 
function; this is a change from the /usr/group Standard and previous drafts, 
which included a lockf() function. Without concurrency controls, this feature 
may not be fully utilized without occasional loss of data. Since other mechan- 
isms for creating critical regions, such as semaphores, are not included, a file 
record locking mechanism was thought appropriate. The fcntl() mechanism 
may be used to implement semaphores, although access is not first-in-first-out 
without extra application development effort. 

Data losses occur in several ways. One is that read and write operations are 
not atomic, and as such a reader may get segments of new and old data if con- 
currently written by another process. Another occurs when several processes 
try to update the same record, without sequencing controls; several updates 
may occur in parallel and the last writer will “win.” Another case is a b-tree or 
other internal list-based database that is undergoing reorganization. Without 
exclusive use to the tree segment by the updating process, other reading 
processes chance getting lost in the database when the index blocks are split, 
condensed, inserted, or deleted. While fentl() is useful for many applications, it 
is not intended to be overly general, and will not handle the b-tree example well. 

This facility is only required for regular files, because it is not appropriate for 
many devices such as terminals and network connections. 

Since fentl() works with “any file descriptor associated with that file, however 
it is obtained,” the file descriptor may have been inherited through a fork() 
§3.1.1 or exec §3.1.2 operation and thus may affect a file that another process 
also has open. 

The use of the open file description to identify what to lock requires extra 
calls and presents problems if several processes are sharing an open file descrip- 
tion but there are too many implementations of the existing mechanism for the 
standard to use different specifications. 

But note that while an open file description may be shared through fork(), 
locks are not inherited through fork(). Yet locks may be inherited through one 
of the exec functions. 
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The identification of a machine in a network environment is outside of the 
scope of this standard. Thus, an /_sysid member, such as found in System V, is 
not included in the locking structure. 

Since locking is performed with fentl(), rather than lockf(), this specification 
prohibits use of advisory exclusive locking on a file that is not open for writing. 

Before successful return from a F_LSETLK or F_LSETLKW request, the previous 
lock type for each byte in the specified region shall be replaced by the new lock 
type. This can result in a previously locked region being split into smaller 
regions. If this would cause the number of regions being held by all processes in 
the system to exceed a system-imposed limit, the fentl() function returns —1 
with errno set to [ENOLCK]. 

Mandatory locking was a major feature of the 1984 /usr/group Standard. 
For advisory file record locking to be effective, all processes that have access to a 
file must cooperate and use the advisory mechanism before doing I/O on the file. 
Enforcement-mode record locking is important when it cannot be assumed that 
all processes are cooperating. For example, if one user uses an editor to update 
a file at the same time that a second user executes another process that updates 
the same file, if only one of the two processes is using advisory locking, the 
processes are not cooperating. Enforcement mode record locking would protect 
against accidental collisions. 

Secondly, advisory record locking requires a process using locking to bracket 
each I/O operation with lock (or test) and unlock operations. With enforcement 
mode file and record locking, a process can lock the file once and unlock when 
all 1/O operations have been completed. Enforcement mode record locking pro- 
vides a base that can be enhanced, for example, with shareable locks. That is, 
the mechanism could be enhanced to allow a process to lock a file so other 
processes could read it but none of them could write it. 

Mandatory locks were omitted for several reasons: 

(1) Mandatory lock setting was done by multiplexing the setgid bit in most 
implementations; this was confusing, at best. 

(2) Relationship to file truncation as supported in 4.2BSD was not well speci- 
fied. 

(3) Any publicly readable file could be locked by anyone. Many historical 
implementations keep the password database in a publicly-readable file. A 
malicious user could thus prohibit logins. Another possibility would be to 
hold open a long-distance telephone line. _ 

(4) Some demand-paged historical implementations offer memory mapped 
files, and enforcement cannot be done on that type of file. 

Since sleeping on a region is interrupted with any signal, alarm() §3.4.1 may 
be used to provide a timeout facility in applications requiring it. This is useful 
in deadlock detection. Because implementation of full deadlock detection is not 
always feasible, the [EDEADLK] error was made optional. 

The /_start element of the flock structure and the offset argument of lseek() 
are, in some cases, taken as signed offsets from some position in a file, but the 
type of these objects is allowed to be unsigned. This apparent conflict is avoided 
by the C Standard’s definitions of conversions from signed to unsigned and of 
arithmetic operations on unsigned types. If U is of type off_t, the expressions 
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U = ((ofm ty) (-a)) 

and 
Sd 

will produce the same result, and, for example, 
lseek (fd, (off t) - 4, SEEK END); 


is well defined. 

B.6.5.3 Reposition Read/Write File Offset. The C Standard includes 
the functions fgetpos() §B.6.5.3 and fsetpos() §B.6.5.3 which work on very large 
files by use of a special positioning type. 

Although /seek() may position the file offset beyond the end of the file, this 
function does not itself extend the size of the file. While the only function in 
POSIX that may extend the size of the file is write() §6.4.2, several Standard C 
functions, such as fwrite(), fprintf(), etc., may do so (by causing calls on write()). 

An illegal file offset that would cause [EINVAL] to be returned may be both 
implementation-defined and device-dependent (for example, memory may have 
few illegal values). A negative file offset may be legal for some devices in some 
implementations. 

See fentl() §B.6.5.2 for a explanation of the use of signed and unsigned offsets 
with lseek(). 


B.7 Device- and Class-Specific Functions. This section has probably 
undergone more debate and revision than any other in the standard. Numerous 
historical implementations were investigated, and at least four major proposals 
were made. 

There are several sources of the difficulties of this section: 

(1) The basic Version 7 ioctl() mechanism is difficult to specify adequately, 
due to its use of a third argument that varies in both size and type according 
to the second, command, argument. 

(2) System III introduced and System V continued ioct/() commands that are 
completely different from those of Version 7. 

(3) 4.2BSD and other Berkeley systems added to the basic Version 7 ioctl() 
command set; some of these were for features such as job control that POSIX 
eventually adopted. 

(4) None of the basic historical implementations are adequate in an interna- 
tional environment. This concern is not technically within the scope of 
POSIX, but the Working Group did not want to supply unnecessary impedi- 
ments to internationalization. 

The 1984 /usr/group Standard attempted to specify a portable mechanism 
that application writers could use to get and set the modes of an asynchronous 
terminal. The intention of that committee was to provide an interface that was 
neither implementation-specific nor hardware dependent. Initial proposals 
dealt with high level routines similar to the curses library (available on most 
historical implementations). In such an implementation, the user interface 
would consist of calls similar to: 
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setraw(); 
setcooked(); 


It was quickly pointed out that if such routines were standardized, the defini- 
tion of “raw” and “cooked” would have to be provided. If these modes were not 
well defined in the standard, application code could not be written in a portable 
way. However, the definition of the terms would force low level concepts to be 
included in a supposedly high level interface definition. 

Recognizing the pitfalls of the high level approach, the Working Group 
focused on the necessary low level attributes that were needed to support the 
necessary terminal characteristics (e.g., line speeds, raw mode, cooked mode, 
etc.). After considerable debate, a structure similar to, but more flexible than, 
the AT&T System III termio was agreed upon. The format of that structure, 
referred to as the termios structure, has formed the basis for the current sec- 
tion. 

A method is needed to communicate with the system about the termios infor- 
mation. Proposals have included: 

(1) The zoc#/l() function as in System V. This has the same problems as men- 
tioned above for the Version 7 ioc#/() function, and is basically identical to it. 
Another problem is that the direction of the command (whether information 
is written from or read into the third argument) is not specified: in historical 
implementations only the device driver knows for sure. This is a problem for 
networked implementations. It is also a problem that there is no size param- 
eter to specify the variable size of the third argument, and similarly for its 
type. 

(2) An ioentl() function with additional arguments specifying direction, type, 
and size. But these new arguments would not help application writers, who 
would have no control over their values, which would have to match each 
command exactly. The new arguments do, however, solve the problems of 
networked implementations. And iocnt/l() is implementable in terms of 
toctl() on historical implementations (without need for modifying existing 
code), although it is easy to update existing code to use the arguments 
directly. 

(3) A termentl() function with the same arguments as proposed for the 
tocntl() function. The difference would be that termcntl() would be limited to 
terminal interface functions: there would be other interface functions, such 
as a tapecnitl() function for tape interfaces, rather than a single general dev- 
ice interface routine. 

(4) Unspecified functions. The issue of what the interface function(s) should 
be called was sidestepped for some time after the Trial Use Standard while 
the Working Group concentrated on the details of the information to be han- 
dled. The resulting specification resembles the information in System V, but 
attempts to avoid problems of case, speed, networks, and internationaliza- 
tion. 

(5) Specific tc*() functions to replace each ioctl() function were finally incor- 
porated into the standard, instead of any of the above-mentioned proposals. 
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The issue of modem control was excluded from POSIX on the grounds that: 
(1) It was concerned with setting and control of hardware timers; 
(2) The appropriate timers and settings vary widely internationally; 
(3) Feedback from X/Open indicated that this facility was not consistent with 
European needs, and that specification of such a facility was not a require- 
ment for portability from their “international perspective.” 


B.7.1 General Terminal Interface. Although the Working Group 
attempted to take into account needs of both interface implementors and appli- 
cation developers throughout the standard, more attention was paid to the 
needs of the latter in this section. This is because, while many aspects of the 
programming interface can be hidden from the user by the application 
developer, the terminal interface is usually a large part of the user interface. 
Although to some extent the application developer can build missing features or 
work around inappropriate ones, the difficulties of doing that are greater in the 
terminal interface than elsewhere. For example, efficiency prohibits the aver- 
age program from interpreting every character passing through it in order to 
simulate character erase, line kill, etc. These functions should usually be done 
by the operating system, possibly at interrupt level. 

The tc*() functions were introduced as a way of avoiding the problems 
inherent in the traditional ioctl() §B.7.1 function and in variants of it that were 
proposed. For example, tcsetattr() is specified in place of the use of the TCSETA 
ioctl() command function. This allows specification of all the arguments in a 
manner consistent with the C Standard, unlike the varying third argument of 
toctl(), which is sometimes a pointer (to any of many different types) and some- 
times an int. 

The advantages of this new method include: 

(1) It allows strict type checking. 
(2) The direction of transfer of control data is explicit. 
(3) Portable capabilities are clearly identified. 
(4) The need for a general interface routine is avoided. 
(5) Size of the argument is well-defined (there is only one type). 
The disadvantages include: 
(1) No historical implementation uses the new method. 
(2) There are many small routines instead of one general-purpose one. 
(3) The historical parallel with fentl() §6.5.2 is broken. 
B.7.1.1 Interface Characteristics. 

B.7.1.1.1 Opening a Terminal Device File. Further implications of 
the effects of CLOCAL are discussed in Control Modes §7.1.2.4. 

B.7.1.1.2 Process Groups. 

B.7.1.1.3 The Controlling Terminal. The standard does not specify a 
mechanism by which to allocate a controlling terminal. This is normally done 
by a system utility (such as getty) and is considered an administrative feature 
outside the scope of this standard. 

Traditional implementations allocate controlling terminals on certain open() 
calls. Since open() is part of the standard, its behavior had to be dealt with. 
The Working Group did not wish to require the traditional behavior, because it 
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is not very straightforward or flexible for either implementations or applica- 
tions. However, because of its prevalence, it was not practical to disallow this 
behavior either. Thus a mechanism was standardized to ensure portable, 
predictable behavior in open() §B.5.3.1. 

B.7.1.1.4 Terminal Access Control. The access controls described in 
this section apply only to a process that is accessing its controlling terminal. A 
process accessing a terminal that is not its controlling terminal is effectively 
treated the same as a member of the foreground process group. While this may 
seem unintuitive, note that these controls are for the purpose of job control, not 
security, and job control relates only to a process’s controlling terminal. Normal 
file access permissions handle security. 

If the process calling read() or write() is in a background process group that is 
orphaned, it is not desirable to stop the process group, as it is no longer under 
the control of a job control shell which could put it into foreground again. 
Accordingly, calls to read() or write() functions by such processes receive an 
immediate error return. This is different than in 4.2BSD, which kills orphaned 
processes which receive terminal stop signals. 

The foreground/background/orphaned process group check performed by the 
terminal driver must be repeatedly performed until the calling process moves 
into the foreground or until the process group of the calling process becomes 
orphaned. That is, when the terminal driver determines that the calling process 
is in the background and should receive a job control signal, it sends the 
appropriate signal (SIGTTIN or SIGTTOU) to every process in the process group 
of the calling process and then it allows the calling process to immediately 
receive the signal. The latter is typically performed by blocking the process so 
that the signal is immediately noticed. Note, however, that after the process 
finishes receiving the signal and control is returned to the driver, the terminal 
driver must reexecute the foreground/background/orphaned process group 
check. The process may still be in the background, either because it was contin- 
ued in the background by a job control shell, or because it caught the signal and 
did nothing. 

The terminal driver repeatedly performs the  foreground/back- 
ground/orphaned process group checks whenever a process is about to access the 
terminal. In the case of write() or the Control Functions §7.2, the check is 
performed at the entry of the function. In the case of read(), the check is per- 
formed not only at the entry of the function but also after blocking the process to 
wait for input characters (if necessary). That is, once the driver has determined 
that the process calling the read() function is in the foreground, it attempts to 
retrieve characters from the input queue. If the queue is empty, it blocks the 
process waiting for characters. When characters are available and control is 
returned to the driver, the terminal driver must return to the repeated fore- 
ground/background/orphaned process group check again. The process may have 
moved from the foreground to the background while it was blocked waiting for 
input characters. 

See also job control §B.2.3. 
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B.7.1.1.5 Input Processing and Reading Data. 

B.7.1.1.6 Canonical Mode Input Processing. The term “character” 
is intended here. ERASE should erase the last character, not the last byte. In 
the case of multibyte characters, these two may be different. 

4.3BSD has a WERASE character that erases the last “word” typed (but not 
any preceding blanks or tabs). A word is defined as a sequence of non-blank 
characters, with tabs counted as blanks. Like ERASE, WERASE does not erase 
beyond the beginning of the line. This WERASE feature has not been specified 
in the standard because it is difficult to define in the international environment. 
It is only useful for languages where words are delimited by blanks. In some 
ideographic languages, such as Japanese and Chinese, words are not delimited 
at all. The WERASE character should presumably take one back to the begin- 
ning of a sentence in those cases: practically, this means it would not get much 
use for those languages. 

B.7.1.1.7 Non-Canonical Mode Input Processing. Some points to 
note about MIN and TIME: 

(1) In the preceding explanations one may notice that the interactions of MIN 
and TIME are not symmetric. For example, when MIN > 0 and TIME = 0, 
TIME has no effect. However, in the opposite case where MIN = 0 and TIME > 
0, both MIN and TIME play a role in that MIN is satisfied with the receipt of a 
single character. 

(2) Also note that in case A (MIN > 0, TIME > 0), TIME represents an inter- 
character timer while in case C (MIN = 0, TIME > 0) TIME represents a read 
timer. 

These two points highlight the dual purpose of the MIN/TIME feature. Cases 
A and B, where MIN > 0, exist to handle burst mode activity (e.g., file transfer 
programs) where a program would like to process at least MIN characters at a 
time. In case A, the intercharacter timer is activated by a user as a safety meas- 
ure; while in case B, it is turned off. 

Cases C and D exist to handle single character timed transfers. These cases 
are readily adaptable to screen-based applications that need to know if a charac- 
ter is present in the input queue before refreshing the screen. In case C the 
read is timed; while in case D, it is not. 

Another important note is that MIN is always just a minimum. It does not 
denote a record length. That is, if a program does a read of 20 bytes, MIN is 10, 
and 25 characters are present, 20 characters shall be returned to the user. 

B.7.1.1.8 Writing Data and Output Processing. 

B.7.1.1.9 Special Characters. 

B.7.1.1.10 Modem Disconnect. 

B.7.1.1.11 Closing a Terminal Device File. 

B.7.1.2 Settable Parameters. 

B.7.1.2.1 termios Structure. This structure is part of an interface 
which in general retains the historic grouping of flags. Although a more optimal 
structure for implementations may be possible, the degree of change to applica- 
tions would be significantly larger. 
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B.7.1.2.2 Input Modes. Some historical implementations treated a 
long break as multiple events, as many as one per character time. The wording 
in the standard explicitly prohibits this. 

Although the ISTRIP flag is normally superfluous with today’s terminal 
hardware and software, it is historically supported. Therefore, applications may 
be using ISTRIP, and there is no technical problem with supporting this flag. 
Also, applications may wish to receive only 7-bit input bytes, and may not be 
connected directly to the hardware terminal device (for example, when a connec- 
tion traverses a network). 

Also, there is no requirement in general that the terminal device ensure that 
high-order bits beyond the specified character size are cleared. ISTRIP provides 
this function for 7-bit characters, which are common. 

In dealing with multibyte characters, the consequences of a parity error in 
such a character, or worse in an escape sequence affecting the current character 
set, are beyond the scope of this standard and are best dealt with by the applica- 
tion processing the multibyte characters. 

B.7.1.2.3 Output Modes. This standard does not describe postprocess- 
ing of output to a terminal, or detailed control of that from a portable applica- 
tion. (That is, translation of newline to carriage return followed by linefeed or 
tab processing.) There is nothing that a portable application should do to its 
output for a terminal because that would require knowledge of the operation of 
the terminal. It is the responsibility of the operating system to provide postpro- 
cessing appropriate to the output device, whether it is a terminal or some other 
type of device. 

Extensions to the standard to control the type of postprocessing already exist, 
and are expected to continue into the future. The control of these features is 
primarily to adjust the interface between the system and the terminal device so 
the output appears on the display correctly. This should be set up before use by 
any application. 

In general, both the input and output modes should not be set absolutely, but 
rather modified from the inherited state. 

B.7.1.2.4 Control Modes. 

B.7.1.2.5 Local Modes. Non-canonical mode is provided to allow fast 
bursts of input to be read efficiently while still allowing single character input. 

The ECHONL function has historically been in many implementations. Since 
there seems to be no technical problem with supporting ECHONL it is included 
in the standard to increase consensus. 

The alternate behavior possible when ECHOK or ECHOE are specified with 
ICANON is permitted as a compromise depending on what the actual terminal 
hardware can do. Erasing characters and lines is preferred, but is not always 
possible. 

B.7.1.2.6 Special Control Characters. Permitting VMIN and VTIME 
to overlap with VEOF and VEOL was a compromise for existing implementa- 
tions. Only when backwards compatibility of object code is a serious concern to 
an implementor should an implementation continue this practice. Correct 
applications which work with the overlap (at the source level) should also work 
if it is not present, but not the reverse. 
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B.7.1.2.7 Baud Rate Functions. The term baud is used historically 
here, but is not technically correct. This is properly “bits per second,” which 
may not be the same as “baud.” However, the term is used because of the his- 
torical usage and understanding. 

These functions do not take numbers as arguments, but rather symbolic 
names. There are two reasons for this: historically numbers were not used 
because of the way the rate was stored in the data structure. This is retained 
even though an interface function is now used. Secondly, and more importantly, 
only a limited set of possible rates is at all portable, and this constrains the 
application to that set. There is nothing to prevent an implementation to 
accept, as an extension, a number (such as 126) if it wished, and because the 
encoding of the Bxxx symbols is not specified, this can be done so no ambiguity 
is introduced. 

The standard specifies that if an attempt to set the input baud rate to zero is 
made by cfsetispeed(), the input baud rate will be instead set to the output baud 
rate by cfsetispeed(). This allows implementations to provide support for split 
baud rates or not. 

In historical implementations, the baud rate information is traditionally kept 
in c_cflag. Applications should be written to presume that this might be the 
case (and thus not blindly copy c_cflag) but not to rely on it, in case it is in some 
other field of the structure. Setting the c_cflag field absolutely after setting a 
baud rate is a bad idea because of this. In general, the unused parts of the flag 
fields might be used by the implementation, and should not be blindly copied 
from the descriptions of one terminal device to another. 


B.7.2 General Terminal Interface Control Functions. The restrictions 
described in this section on access from processes in background process groups 
controls apply only to a process that is accessing its controlling terminal. (See 
Terminal Access Control §B.7.1.1.5). 

Care must be taken when changing the terminal attributes. Applications 
should always do a tcgetattr(), save the termios structure values returned, and 
then do a tcsetattr() changing only the necessary fields. The application should 
use the values saved from the tcgetattr() to reset the terminal state whenever it 
is done with the terminal. This is necessary because terminal attributes apply 
to the underlying port, and not to each individual open instance; that is, all 
processes that have used the terminal see the latest attribute changes. 

A program which uses these functions should be written to catch all signals 
and take other appropriate actions to assure that when the program terminates, 
whether planned or not, the terminal device’s state is restored to its original 
state. Not doing this is at best antisocial. See also General Terminal Inter- 
face §B.7.1. 

B.7.2.1 Get and Set State. 
B.7.2.2. Line Control Functions. 
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B.7.2.3. Get Foreground Process Group ID. The tcgetpgrp() function 
has identical functionality to the 4.2BSD ioct/() function TIOCGPGRP except for 
the additional security restriction that the referenced terminal must be the con- 
trolling terminal for the calling process. 

B.7.2.4 Set Foreground Process Group ID. The tcsetpgrp() function 
has identical functionality to the 4.2BSD ioct/]() function TIOCSPGRP except for 
the additional security restrictions that the referenced terminal must be the 
controlling terminal for the calling process and the specified new process group 
must be currently in use in the caller’s session. 

See the discussion of C functions in POSIX and the C Standard §B.1.4. 


B.8 Language-Specific Services for the C Programming Language. 
Common usage may be defined by historical publications as The C Program- 
ming Language, by Kernighan and Ritchie, listed in Bibliographic Notes 
§B.11. 

The null set of supported languages is allowed. 

The list of functions comprises the list of “common usage” functions, plus 
those that are not in common usage that are addressed by this standard. The 
rules for common usage conformance to the standard address whether the func- 
tions that are not generally considered in common usage are implemented. 
There are a large number of functions found in various systems that. although 
frequently found, are not broadly enough available to be considered in common 
usage. The signa/() function (although in common usage) is omitted because it 
is the belief of the working group that programs conforming to POSIX should use 
sigaction() instead. 


B.8.1 Referenced C Language Routines. 
B.8.1.1 Extensions to Time Functions. System V uses the TZ environ- 
ment variable to set some information about time. It has the form (spaces 
inserted for clarity): 


std offset dst 


where the first three characters (std) are the name of the standard time zone, 
the digits which follow (offset) represent the time added to the local time zone to 
arrive at Coordinated Universal Time, and the next three characters (dst) are 
the name of the summer time zone. The meaning of offset implies that most 
sites west of the Prime Meridian will have a positive offset (preceded by an 
optional plus sign, “+”), while most sites east of the Prime Meridian will have a 
negative offset (preceded by a minus sign, “—”). Both std and offset are required: 
if dst is missing, summer time does not apply. 

Currently, the UNIX system Jocaltime() function translates a number of 
seconds since the Epoch §2.3 into a detailed breakdown of that time. This 
breakdown includes: 

(1) Time of day: Hours, minutes, and seconds. 

(2) Day of the month, month of the year, and the year. 

(3) Day of the week and day of the year (Julian day). 

(4) Whether or not summer (daylight saving) time is in effect. 
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It is the first and last items that present a nasty problem: The time of the day 
depends on whether or not summer time is in effect. Whether or not summer 
time is in effect depends on the locale and date. 

Most historical systems had time zone rules compiled into the C library. 
These rules usually represented United States rules for 1970 to 1986. This did 
not accommodate the changes of 1987, nor other world variations (-hour time, 
double daylight time, and solar time being common but not complete examples). 
Some recent systems addressed these problems in various ways. 

Having the rules compiled into the program made binary distributions that 
accommodated all the variations (including sudden changes to the law), and 
per-process rule changes, difficult at best. 

The current standard includes a way of specifying the time zone in the TZ 
string, but only permits one time zone pattern at a time, thus not dealing with 
different patterns in previous years, and does not deal with such issues as solar 
time. Methods exist to deal with all the problems above. The method in this 
standard appears to be simpler to implement and may be faster in execution 
when it is adequate. 

The current standard also permits an implementation-defined rule set which 
begins with a colon. (The previous format cannot begin with a colon.) 

Rules of the form AAAn or AAAnBBB (the style used in many historical imple- 
mentations) do not carry with them any statement about the start and end of 
daylight time (neither the date nor the time of day; the default to 02:00 not 
applying if no rule is present at all), thus implying that the implementation 
must provide the appropriate rules. An implementation may provide those 
rules in any way it sees fit, as long as the constraints implied by the TZ string as 
provided by the user are met. Specifically the implementation may use the 
string as an index into a table, which may reside either on disk or in memory. 
Such tables could contain rules which are sensitive to the year to which they are 
applied, again since the user did not specify the exact rule. (Although impracti- 
cal, every possible TZ string could be represented in a table, as a detail of imple- 
mentation; the less specific the user is about the TZ string, the more freedom 
the implementation has to interpret it.) 

There is at least one public domain time zone implementation (the 
Olson/Harris method) that uses non-specific TZ strings and a table, as described 
above and handles all the general time zone problems mentioned above. This 
implementation also appears in a late release of 4.3BSD. If this implementation 
honors all the specifications provided in the TZ string it would conform to the 
standard. Nothing precludes the implementation from adding information 
beyond that given by the user in the TZ string. 

The fully-specified TZ environment variable extends the historical meaning to 
also include a rule for when to use standard time and when to use summer time. 
Southern hemisphere time zones are supported by allowing the first rule date 
(change to summer time) to be later in the year than the second rule date 
(change to standard time). 

This mechanism accommodates the “floating day” rules (for example “last 
Sunday in October”) used in the U.S. and Canada (and the European Economic 
Community for the last several years). In theory, TZ only has to be set once and 
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then never touched again unless the law is changed. 

Julian dates are proposed with two syntaxes, one zero-based, the other one- 
based. They are here for historical reasons. The one-based counting (J) is used 
more commonly in Europe (and on calendars people may use for reference). The 
zero-based counting (n) is used currently in some implementations and should 
be kept for historical reasons as well as being the only way to specify Leap day. 

It is expected the leading colon format will allow systems to implement an 
even broader range of specifications for the time zone without having to resort 
to a file, or to permit naming an explicit file containing the appropriate rules. 

The specification in the standard for TZ assumes that very few programs need 
to be historically accurate as long as the relative timing of two events is 
preserved. 

Summer time is governed by both locale and date. This proposal only handles 
the locale dependency. Using an implementation-defined file format for either 
the entire TZ variable or to specify the rules for a particular time zone is allowed 
as a means by which both the locale and date dependency can be handled. 

Since historical implementations do not examine TZ beyond the assumed end 
of dst, it is possible to literally extend TZ and break very little existing software. 
Since much historical software doesn’t work anyway outside the U.S. time 
zones, minor changes to TZ (such as extending offset to be hh:mm—as long as 
the colon and minutes, :mm, are optional) should have little effect. 

B.8.1.2 Extensions to setlocale() Function. The C Standard defines a 
collection of interfaces to support internationalization. One of the most signifi- 
cant aspects of these interfaces is a facility to set and query the international 
environment. The international environment is a repository of information that 
affects the behavior of certain functionality, namely: 

(1) Character Handling 

(2) String Handling (i.e., collating) 
(3) Date/Time Formatting 

(4) Numeric Editing. 

The setlocale() function provides the application developer with the ability to 
set all or portions, called categories, of the international environment. These 
categories correspond to the areas of functionality, mentioned above. The syn- 
tax for setlocale() is the following: 


emae, *setillocale (category, locale) 
ions category; 
char *locale 


where category is the name of one of five categories, namely: 


LC_CTYPE 
LC_COLLATE 
LC_TIME 
LC_MONETARY 
LC_NUMERIC 


In addition, a special value, called LC_ALL, directs setlocale() to set all 
categories. 
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The locale argument is a character string that points to a specific setting for 
the international environment, or locale. There are three preset values for the 
locale argument, namely: 

et Specifies the minimal environment for C translation. If setlo- 
cale() is not invoked, the "C” locale is the default. 

aS Specifies an implementation-defined native environment. 

NULL Used to direct setlocale() to query the current international 
environment and return the name of the locale. 

This section describes the behavior of an implementation of setlocale() and its 
use of environment variables in controlling this behavior on POSIX-based sys- 
tems. There are two primary uses of setlocale(): 

(1) Querying the international environment to find out what it is set to; 
(2) Setting the international environment, or locale, to a specific value. 

The following subsections describe the behavior of setlocale() in these two 
areas. Since it is difficult to describe the behavior in words, examples will be 
used to illustrate the behavior of specific uses. 

To query the international environment, setlocale() is invoked with a specific 
category and the NULL pointer as the locale. The NULL pointer is a special 
directive to setlocale() that tells it to query rather than set the international 
environment. Below is the syntax for using setlocale() to query the name of the 
international environment: 


LC_ALL 
ECECTYVER 
LC_COLLATE 
setlocale ( LC TIME 
LC_NUMERIC 
LC_MONETAR 


nichar = ONO ele). 


The setlocale() function returns the string corresponding to the current inter- 
national environment. This value may be used by a subsequent call to setlo- 
cale() to reset the international environment to this value. However, it should 
be noted that the return value from setlocale() is a pointer to a static area 
within the function and is not guaranteed to remain unchanged (i.e., it may be 
modified by a subsequent call to setlocale()). Therefore, if the purpose of calling 
setlocale() is to save the value of the current international environment so it can 
be changed and reset back later, the return value should be copied to a charac- 
ter array in the calling program. 

There are three ways to set the international environment with setlocale(): 

setlocale (category, string) 
This usage will set a specific category in the international 
environment to a specific value corresponding to the value of 
the string. A specific example is provided below: 


set loca lle Gh y Ais) ae Pearce ome, 
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In this example, all categories of the international environ- 
ment will be set to the locale corresponding to the string 
"Fr FR.8859", or the French language as spoken in France 
using the ISO 8859/1 code set. 

If the string does not correspond to a valid locale, setlocale() 
will return a NULL pointer and the international environment 
is not changed. Otherwise, setlocale() will return the name of 
the locale just set. 

setlocale (category, "C") 
The C Standard draft proposal states that one locale must exist 
on all conforming implementations. The name of the locale is 
"Cc", and corresponds to a minimal international environment 
needed to support the C programming language. 

setlocale (category, "") 
This will set a specific category to an implementation-defined 
default. For POSIX-based systems, this corresponds to the value 
of the environment variables. 


B.8.2 FILE-Type C Language Functions. 

B.8.2.1 Map a Stream Pointer to a File Descriptor. Without some 
specification of which file descriptors are associated with these streams, it is 
impossible for an application to set up the streams for another application it 
starts with fork() §3.1.1 and exec §3.1.2. In particular, it would not be possible 
to write a portable version of the sh command processor (although there may be 
other constraints that would prevent that portability). 

B.8.2.2. Open a Stream on a File Descriptor. The file descriptor may 
have been obtained from open() §5.3.1, creat() §5.3.2, pipe() §6.1.1, dup() §6.2.1, 
fentlQ §6.5.2, or inherited through fork() §3.1.1 or exec §3.1.2, or perhaps 
obtained by implementation-dependent means, such as the 4.3BSD socket () call. 

The meanings of the type arguments of fdopen() and fopen() differ. With fdo- 
pen(), open for write ("w" or "w+") does not truncate and append ("a" or "a+") 
cannot create for writing. There is no need for "b" in the format due to the 
equivalence of binary and text files in POSIX. See Text vs. binary file modes 
§B.1.4. 

B.8.2.3 Interactions of Other FILE-Type C Functions. Note that the 
existence of open streams on a file implies open file descriptors, and thus affects 
the timestamps of the file. The intent is that using stdio routines to read a file 
must eventually update the access time, and using them to write a file must 
eventually update the modify and change times. However, the exact timing of 
marking the st_atime, st_ctime, and st_mtime fields cannot be specified, as that 
would be tantamount to mandating a particular buffering strategy. 

The purpose of the rules about handles is to give the application writer a 
fighting chance of writing a program that uses stdio and does some shell-like 
things, in particular create an open file for a child process to use, where both the 
parent and child wish to use stdio, with the consequences of buffering. This in 
most cases cannot happen in Standard C (because there is no way to create a 
second handle), but the system() function can cause this to occur, at least in 


B.8 Language-Specific Services for the C Programming Language. 269 


IEEE 
Std 1003.1-1988 IEEE STANDARD PORTABLE OPERATING SYSTEM 


most historical implementations. 

There are some implied rules about inter-process synchronization, but no 
mechanism is given, intentionally. In the simplest case, if the parent meets the 
requirements on all its files, and then performs a fork() and a wait() before 
further activity on them (and a fflush() on input files after that), the synchroni- 
zation desired will be achieved. Synchronization could in theory be done with 
signals, but the only likely case is the one just described. The terms handle and 
active handle were required to make the text readable, and are not intended for 
use outside this discussion. 

Note that since exit() implies _exit(), a file descriptor is also closed by exit(). 

Because a handle is either freshly opened, or if not must have handed off con- 
trol of the open file description as specified, the new handle is always ready to 
be used (except for seeks), with no initialization. (A freshly opened stream has 
not yet done any reads, as required by Standard C, at least implicitly by the 
rules associated with setvbuf().) 

In requiring the seek to an appropriate location for the new handle, the appli- 
cation is required to know what it is doing if it is passing streams around with 
seeks involved. If the required seek is not done, the results are undefined (and 
in fact the program probably won’t work on many common implementations). 

A naive program used as a utility can be reasonably expected to work properly 
when the constraints are met by the calling program, because it will not hand 
off file descriptors except with closes. 

The exec functions are treated specially, because the application should 
always fflush() everything before performing one of the exec functions. If stdout 
is available on the same open file description after the exec, it is a different 
stream, at least because any unflushed data will be discarded during the exec. 
(Similarly for stdin.) Process termination is also special because a process ter- 
minating due to a signal or _exit() will not have the buffers flushed. 

The standard does not specify asynchronous I/O, and when dealing with asyn- 
chronous I/O the problem of coordinating access to streams will be more difficult. 
If asynchronous I/O is provided as an extension, the problems it introduces in 
this area should be addressed as part of that extension. 

It may be that functions such as system() and popen(), currently being con- 
sidered by P1003.2, will have to perform some of these operations. 

The introduction of underlying functions allows generic reference to errno 
values returned by those functions, and also to other side effects (as required in 
the handles discussion above). It is not intended to specify implementation, 
although many implementations may in fact use those functions. Standard C 
says very little about errno in the context of stdio. In the more restricted POSIX 
environment, providing a reasonable set of errno values become possible. 

Specifying the semantics with respect to line buffered streams is difficult . 
because specifying exactly what a line is gets complex. Rather than respecify it, 
the semantics of fgets() and fputs() are used, as they have the right conceptual 
effect. The problem with this is that ordinary files require some kind of reada- 
head to find the separating linefeed. Thus the addition that any implied buffer- 
ing doesn’t exist for the purposes of the discussion. In a typical system, the real 
meaning is “seek back to the last linefeed you actually consumed, assuming you 
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read the file beyond it in the first place.” This cannot be said directly because it 
presumes an ordinary file, which is not presumed in this section; remote access 
to a line-oriented file might be likely. Line-buffered output streams don’t have 
the problem because they cannot buffer back, by definition. 

B.8.2.3.1 fopen(. 

B.8.2.3.2 fclose(). The fclose() function is required to synchronize the 
buffer pointer with the file pointer (unless it already is, which would be the case 
at EOF). Functionality equivalent to: 


fseek (stream, ftell(siream), SEEK SET) 


does this nicely. The exception for devices incapable of seeking is an obvious 
requirement, but the implication is that there is no way to reliably read a buf- 
fered pipe and hand off handles. This is reality as it is in historical implementa- 
tions, and is inherent in any “readahead” buffering scheme. This limitation is 
also reflected in the handle hand-off rules. 

Note that the last byte read from a stream, and the last byte read from an 
open file description are not necessarily the same; in most cases the open file 
description’s pointer will be past that of the stream because of the stream’s rea- 
dahead. 

B.8.2.3.3 freopen(). 

B.8.2.3.4 fflush(). The fflush() function is required to flush its buffers 
on input, and resynchronize the buffer pointer. The reasoning is quite similar to 
fsyne(). Standard C already requires this for input. 

B.8.2.3.5 fgetcQ, fgetsQ, freadQ, getcQ, getchar(), gets, scanfQ, 
fscanf(Q. 

B.8.2.3.6 fputcQ, fputsQ, fwriteQ, putcQ, putchar(Q, putsQ, printfO, 
uprintf{(), ufprintfO. 

B.8.2.3.7 fseek(Q), rewind(). The fseek() function must operate as speci- 
fied, to make the case where seeking is being done work. The key requirement 
is to avoid an optimization such that an fseek() would not result in an /seek() if 
the fseek() pointed within the current buffer. This optimization is valuable in 
general, so it is only required after an fflush(). 

B.8.2.3.8 perror(). 

B.8.2.3.9 tmpfile(). 

B.8.2.3.10 /ftell(Q. 

B.8.2.3.11 Error Reporting. [ENOMEM] was considered for addition 
as an explicit possible error, because most implementations use malloc(). This 
was not done because the scope does not include “out of resource” errors. 
Nevertheless this is the most likely error to be added to the possible error condi- 
tions. Other implementation-defined errors, particularly in the f*open() family, 
are to be expected, and the generic rules about adding (or deleting) possible 
errors apply, except that it is expected that implementation-defined changes in 
the error set returned by open() would also apply to fopen() (unless the condi- 
tion can’t possibly happen in fopen(), which may be possible, but appears 
unlikely.). 
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B.8.2.3.12 exit(, abort(. 
B.8.2.4 Operations on Files — the remove () Function. 


B.8.3. Other C Language Functions. 

B.8.3.1 Non-Local Jumps. The C Standard specifies various restrictions 
on the usage of the setjmp() macro in order to permit implementors to recognize 
the name in the compiler and not implement an actual function. These same 
restrictions apply to the sigsetjmp() macro. 

There are processors that cannot easily support these calls, but the Working 
Group did not consider that a sufficient reason not to include them. 

The distinction between setjmp(/longjmp() and sigsetjmp()/siglongjmp() is 
only significant for programs which use the sigaction(), sigprocmask(), or sig- 
suspend() functions. Since earlier implementations did not have signal masks, 
only a single pair was provided. 

4.2BSD and 4.3BSD systems provide functions named _setjmp() and 
_longjmp() which, together with setjmp(/longjmp(), provide the same func- 
tionality as sigsetjmp()/siglongjmp(). On those systems, setjmp(V/longjmp() 
save and restore signal masks, while _setjmp()/_longjmp() do not. On System V 
Release 3 and in corresponding issues of the SVID, setjmp()/longjmp() are expli- 
citly defined not to save and restore signal masks. In order to permit existing 
practice in both cases, the Working Group decided not to specify the relation of 
setimp()/longjmp() to signal masks and to define a new set of functions instead. 

B.8.3.2 Set Time Zone. 


B.9 System Databases. At one time, this chapter was entitled Passwords, 
but this title was changed as all references to a “password file” were changed to 
refer to a “user database.” 


B.9.1 System Databases. There are no references in the standard to a 
passwd file or a group file and there is no requirement that the group or passwd 
databases be kept in ASCII files. Many large timesharing systems use passwd 
databases that are hashed for speed. Certain security classifications prohibit 
certain information in the passwd database from being publicly readable. 

The encoded password fields were deleted from both the passwd and group 
databases in order to meet the requirements of the US Government NBS Pass- 
word FIPS (Publication 112, Password Usage, dated May 30, 1985, and FIPS con- 
cerns in general). 

The term “encoded” is used instead of “encrypted” in order to avoid the imple- 
mentation connotations (such as reversibility, or use of a particular algorithm) 
of the latter term. 

The functions getgrent(), setgrent(), endgrent(), getpwent(), setpwent(), and 
endpwent() are not included in this standard because they provide a linear data- 
base search capability that is not generally useful (the getpwuid(), getpwnam(), 
getgrgid(), and getgrnam() functions are provided for keyed lookup), and 
because in certain distributed systems, especially those with different authenti- 
cation domains, it may not be possible or desirable to provide an application 
with the ability to browse the system databases indiscriminately. 
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B.9.2 Database Access. 
B.9.2.1 Group Database Access. 
B.9.2.2 User Database Access. 


B.10 Data Interchange Format. 


B.10.1 Archive/Interchange File Format. There are three areas of 
interest associated with file interchange: 

(1) Media. There are other existing standards that define the media used 
for data interchange. 

(2) User Interface. This rightfully should be in the IEEE Std 1003.2 stan- 
dard. 

(3) Format of the Data. None of the 1003 Working Groups address topics 
that match this area. The Working Groups felt that this area is closest to 
the types of things that should be in the IEEE Std 1003.1-1988 document, as 
the level of that document most closely matches the level of data required. 

There appear to be two programs in wide use today, tar and cpio. There are 
large camps of supporters for each program. Four options were considered for 
the standard: 

(1) Make both formats optional. This was considered unacceptable because it 
does not allow any portable method for data interchange. 

(2) Require one format. 

(3) Require one format with the other optional. 

(4) Require both formats. 

Both the Extended cpio and the Extended tar Formats are required by this 
standard. 

There are a number of concerns about defining extensions that are known to 
be required by existing implementations. Failure to specify a consistent method 
to implement these extensions will severely limit portability of the program and, 
more importantly, will create severe confusion if these extensions are later 
standardized. 

Two of these extensions that the Working Group felt should be documented 
are symbolic links, that were defined by 4.2BSD and 4.3BSD systems, and high 
performance (or contiguous) files, that exist in a number of implementations 
and are now being considered for the 1003.4 standard. 

By defining these extensions, implementors are able to recognize these 
features and take appropriate implementation-defined actions for these files. 
For example, a high performance file could be converted to a regular file if the 
system didn’t support high performance files; symbolic links might be replaced 
by normal hard links. 

The Working Group has held to the policy of not defining user interfaces to 
utilities by avoiding any description of a tar or cpio command. The behavior 
of the former command was described in some detail in previous drafts. 

The possibilities for transportable media include, but are not limited to: 

(1) %inch magnetic tape, 9 track, 1600 BPI 
(2) ¥-inch magnetic tape, 9 track, 6250 BPI 
(3) QIC-11, %4-inch streamer tape 
(4) QIC-24, Y-inch streamer tape 
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(5) 5.25-inch floppies, 9 512-byte sectors/track, 96 TPI 
(6) 5.25-inch floppies, 9 512-byte sectors/track, 48 TPI 
(7) IBM 3480 cartridges. 

Specification of such media was considered part of the scope of the Trial Use 
Standard, but has been excluded from the Full Use Standard. 

The utilities are not restricted to work only with transportable media: exist- 
ing related utilities are often used to transport data from one place to another in 
the file hierarchy. 

The formats are included to provide implementation-independent ways to 
move files from one system to another and also to provide ways for a user to 
save data on a transportable medium to be restored at a later date. Unfor- 
tunately, these two goals can contradict each other as system security problems 
are easy to find in tape systems if they are not protected. Thus there are strict 
requirements about how the mechanism to copy files shall react when operated 
by both privileged and nonprivileged users. The general concept is that a 
privileged (historically using the ISUID bit in the file’s mode with the owner UID 
of the file set to super-user) version of the utility (or one operated by a 
privileged user) can be used as a save/restore scheme, but a nonprivileged ver- 
sion is used to interpret media from a different system without compromising 
system security. 

Regardless of the archive format used, guidelines should be observed when 
writing tapes to be read on other systems. Assuming the target system is POSIX 
comformant, archives created should only use definitions found in POSIX (e.g., 
file types, minimum values as found in Chapter 2) and should only use relative 
pathnames (i.e., no leading slash). 

Both tar and cpio formats have traditionally been used for both exchange of 
information and archiving. These formats have a number of features that facili- 
tate archiving, for example, the ability to store information about a file which is 
a device. This standard does not assume this kind of data is portable. It is 
intended that these formats provide for the portable exchange of source infor- 
mation between dissimilar systems. This requires specification of the character 
set to be used (ASCII) when these formats are used to write source information. 

All data written by format-creating utilities and read by format-reading utili- 
ties is an ordered stream of bytes. The first byte of the stream should be first on 
the medium, the second byte second, etc. On systems where the hardware 
swaps bytes or otherwise rearranges the byte stream on output or input, the 
implementor of these utilities must compensate for this, so that the data on the 
storage device retains its ordered nature. 

This standard describes two different formats for data archiving and inter- 
change. Through the balloting process the Working Group found strong support 
for both formats. This is a clear indication of the need for both formats due to 
existing practice. The balloting process has also defined a number of deficien- 
cies of each format. The strong support indicates that these deficiencies are not 
sufficient to remove either format from the standard, but will need to be 
addressed by the Working Group in the future. It was not practical to remedy 
these deficiencies during the balloting process. Considerable thought and 
review must occur before making any changes to these formats. It was felt that 
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the best solution is to advise implementors and application writers of these defi- 
ciencies by documenting them in the rationale and to include both formats in 
the standard. 

The Working Group recognizes the desirability for migration toward one com- 
mon format and has been made aware of some strong inputs to consider both 
formats in light of existing practice, current technology trends and the 1003 
standards activities such as security and high performance systems to develop 
one format that is technically superior. This format will be incorporated into a 
future version of this standard when it is developed. 

The deficiencies that have been identified in the existing formats are as fol- 
lows. The size of a file link is limited to 100 characters in tar. A number of 
fields in the cpio header (c_filesize, c_dev, c_ino, c_mode, and c_rdev) are too 
short to support values that the standard allows these fields to contain. Some 
existing implementations and current trends in development will require the 
ability to represent even larger values in these fields. The cpio format does not 
provide a mechanism to represent the user and group IDs symbolically, and a 
range of implementation-defined file types have not been reserved for the user. 
The cpio format. specification does not reserve any formats for 
implementation-defined usage. The extensions that have been made to cpio for 
this standard are compatible with existing versions of cpio. Correction of some 
of these deficiencies would make existing versions of cpio behave unpredict- 
ably. When these changes are made the cpio magic number will have to be 
changed. 

This chapter uses the term file name, which is actually a defined term in 
P1003.2. Note that filename and file name are not synonyms; the latter is a 
synonym for pathname, in that it includes the slashes between filenames. 

In earlier drafts, the word “local” was used in the context of “file system” and 
was taken (incorrectly) to be related to “remotely-mounted file system.” This 
was not intended. The term “(local) file system” refers to the file hierarchy as 
seen by the utilities, and “local” was removed because of this confusion. 

B.10.1.1 Extended tar Format. The original model for this facility is 
the 4.3BSD or Version 7 tar program and format, but the format given here is 
an extension of the traditional tar format. The name USTAR was adopted to 
reflect this. 

This description reflects numerous enhancements over previous versions. 
The goal of these changes was not only to provide the functional enhancements 
desired, but to retain compatibility between new and old versions. This compa- 
tibility has been retained. Archives written using the old archive format are 
compatible with the new format. Archives written using this new format may 
be read by applications designed to use the old format as long as the functional 
enhancements provided here are not used. This means the user is limited to 
archiving only regular type files and nonsymbolic links to such files. 

Implementors should be aware that the previous file format did not include a 
mechanism to archive directory type files. For this reason, the convention of 
using a file name ending with slash was adopted to specify a directory on the 
archive. 
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Note that the total size of the name and prefix fields have been set to meet the 
minimum requirements for {PATH_MAX}. If a pathname will fit within the 
name field, it is recommended that the pathname be stored there without the 
use of the prefix field. Although the name field is known to be too small to con- 
tain {PATH _MAX} characters, the value was not changed in this version of the 
archive file format to retain backward compatibility and instead the prefix was 
introduced. Also because of the earlier version of the format, there is no way to 
remove the limitation on the linkname field being limited in size to just that of 
the name field. 

The size field is required to be meaningful in all implementation extensions, 
although it could be zero. This is required so that the data blocks can always be 
properly counted. 

It is suggested that if device special files need to be represented which cannot 
be represented in the standard format that one of the extension types (‘A’-’2’) 
be used, and that the additional information for the special file be represented 
as data, and be reflected in the size field. 

Attempting to restore a special file type, where it is converted to ordinary 
data and it conflicts with an existing file name, need not be specially detected by 
the utility. If run as an ordinary user, a format-reading utility should not be 
able to overwrite the entries in (say) /dev in any case (whether the file is con- 
verted to another type or not). If run as a privileged user, it should be able to do 
so, and it would be considered a bug if it did not. The same is true of ordinary 
data files and similarly-named special files; it is impossible to anticipate the 
user’s needs (who could really intend to overwrite the file), so the behavior 
should be predictable (and thus regular) and rely on the protection system as 
required. 

The values ’2’ and ’7’ in the typeflag field are intended to define how symbolic 
links and contiguous files can be stored in a tar archive. The standard does not 
require the symbolic link or contiguous file extensions, but does define a stan- 
dard way of archiving these files so that all conforming systems can interpret 
these file types in a meaningful and consistent manner. On a system which 
does not support extended file types, the format-interpreting utility should do 
the best it can with the file and go on to the next. 

B.10.1.2 Extended cpio Format. The model for this format is the exist- 
ing System V cpio -—c data interchange format. This model documents the 
portable version of cpio format and not the binary version. It has the flexibil- 
ity to transfer data of any type described within the POSIX standard, yet is 
extensible to transfer data types specific to extensions beyond POSIX (e.g., sym- 
bolic links or contiguous files). Because it describes existing practice, there is no 
question of maintaining upward compatibility. 

This section does not standardize behavior for the utility when the file type is 
not understood or supported. It is useful for the utility to report to the user 
whatever action is taken in this case, though the standard neither requires nor 
recommends this. 
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B.10.1.2.1 Header. There has been some concern that the size of the 
c_ino field of the header is too small to handle those systems which have very 
large i-node numbers. However, the c_ino field in the header is used strictly as 
a hard link resolution mechanism for archives. It is not necessarily the same 
value as the i-node number of the file in the location that file is extracted from. 

B.10.1.2.2 File Name. For most current implementations of the cpio 
utility, {(PATH_MAX} bytes can be used to describe the pathname without the 
addition of any other header fields (the null byte would be included in this 
count). {PATH_MAX} is the minimum value for pathname size, documented as 
256 bytes in Chapter 2 of the standard. However, an implementation may use 
c_namesize to determine the exact length of the pathname. With the current 
description of the cpio header, this pathname size can be as large as a number 
which is described in six octal digits. 

B.10.1.2.3 File Data. 

B.10.1.2.4 Special Entries. These are provided to maintain backward 
compatibility. 

B.10.1.2.58 cpio Values. Three values are documented under the 
c_mode field values to provide for extensibility for known file types: 

0110000 Reserved for contiguous files. The implementation may treat 
the rest of the information for this archive like a regular file. If 
this file type is undefined, the implementation may create the 
file as a regular file. 

0120000 Reserved for files with symbolic links. The implementation may 
store the link name within the data portion of the file. If this 
type is undefined, the implementation may not know how to 
link this file or be able to understand the data section. The 
implementation may decide to ignore this file type and output a 
warning message. 

0140000 Reserved for sockets. If this type is undefined on the target sys- 
tem, the implementation may decide to ignore this file type and 
output a warning message. 

This provides for extensibility of the cpio format while allowing for the abil- 
ity to read old archives. Files of an unknown type may be read as “regular files” 
on some implementations. On a system which does not support extended file 
types, the format-interpreting utility should do the best it can with the file and 
go on to the next. ; 

B.10.1.3 Multiple Volumes. Multi-volume archives have been intro- 
duced in a manner that has become a de facto standard in many implementa- 
tions. Though it is not required by POSIX, classical implementations of the 
format-reading and -creating utility, upon reading logical end-of-file, check to 
see if an error channel is open to a controlling terminal. The utility then pro- 
duces a message requesting a new medium to be made available. The utility 
waits for a new medium to be made available by attempting to read a message 
to restart from the controlling terminal. In all cases, the communication with 
the controlling terminal is in an implementation-defined manner. 

The section Multiple Volumes §10.1.3 is intended to handle the issue of mul- 
tiple volume archives. Since the end-of-medium and transition between media 
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are not properly part of this standard, the transition is described in terms of 
files; the word “file” is used in a very broad, but correct, sense—a tape drive is a 
file. 

The intent is that files will be read serially until the end-of-archive indication 
is encountered, and that file or media change will be handled by the utilities in 
an implementation-defined manner. 

Note that there was an issue with the representation of this on meiciiic tape, 
and the standard is intended to be interpreted such that each byte of the format 
is represented on the media exactly once. In some current implementations, it 
is not deterministic whether encountering the end-of-medium reflector foil on 
magnetic tape during a write will yield an error during a subsequent read() of 
that record, or if that record is actually recorded on the tape. It is also possible 
that read() will encounter the end-of-medium when end-of-medium was not 
encountered when the data was written. This has to do with conditions where 
the end of [magnetic] record is in such a position that the reflector foil is on the 
verge of being detected by the sensor and is detected during one operation and 
not on a later one, or vice-versa. 

An implementation of the format-creating utility must assure when it writes a 
record that the data appears on the tape exactly once. This implies that the pro- 
gram and the tape driver work in concert. An implementation of the format- 
reading utility must assure that an error in a boundary condition described 
above will not cause loss of data. 

The general consensus was that the following would be considered as correct 
operation of a tape driver when end-of-medium is detected: 

(1) During writing, either: 

(a) The record where the reflector spot was detected is backspaced over by 
the driver so that the trailing tape mark that will be written on close() 
will overwrite. Writing the tape mark should not yield an end-of-medium 
condition. 

(b) Or, the condition is reported as an error on the write() following the 
one where the end-of-medium is detected (the one where the end-of- 
medium is actually detected completing successfully). No data will be 
actually transferred on the write() reporting the error. The subsequent 
close() would write() a tape mark following the last record actually writ- 
ten. Writing the tape mark, and writing any subsequent records, should 
not yield any end-of-medium conditions. 

(The latter behavior permits the implementation of ANSI standard labels 
because several records (the trailer records) can be written after the end-of- 
medium indications. It also permits dealing with, for example, COBOL “ON” 
statements.) 

(2) During reading, the end-of-medium indicator is simply ignored, presum- 
ing that a tape mark (end-of-file) will be recorded on the magnetic medium, 
and the reflector foil was advisory only to the write(). 

Systems where these conditions are not met by the tape driver should assure 
that the format-creating and -reading utilities assure proper representation and 
interpretations of the files on the media, in a way consistent with the above 
recommendations. 
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The typical failures on systems that do not meet the above conditions are 
either: 

(1) To leave the record written when the end-of-medium is encountered on 
the tape, but to report that it was not written. The format-creating utility 
would then rewrite it, and then the format-reading utility could see the 
record twice if the end-of-medium is not sensed during the read operations. 
(2) Or, the write() occurs uneventfully, but the read() senses the error and 
does not actually see the data, causing a record to be omitted. 

Nothing in this standard requires that end-of-medium be determined by any- 
thing on the medium itself (for example, a predetermined maximum size would 
be an acceptable solution for the format creating utility). The format-reading 
utility must be able to read() tapes written by machines that do use the whole 
medium, however. 

On media where end-of-medium and end-of-file are reliably coincident, such 
as disks, end-of-medium and end-of-file can be treated as synonyms. 

Note that partial physical records (corresponding to a single write()) can be 
written on some media, but that only full physical records will actually be writ- 
ten to magnetic tape, given the way the tape operates. 


B.11 Bibliographic Notes. There are far more related papers and books than 
are mentioned here, and some of them may be as good or better. 


B.11.1 Related Standards. The standard assumes that any terms not 
defined in Chapter 2 are defined in the IEEE Standard Dictionary of Electrical 
and Electronics Terms, IEEE Std 100-1977. 

The 1984 /usr/group Standard may be ordered from 


/usr/group Standards Committee 
4655 Old Ironsides Drive, Suite 200 
Santa Clara, California 95054 

(408) 986-8840 


The basic historical reference on the C language is 
e Kernighan, Brian W. and Ritchie, Dennis M., The C Programming 
Language, Prentice-Hall, Englewood Cliffs, New Jersey (1978). 


B.11.2 Historical Implementations. A principal ancestor of all the histor- 
ical implementations is the Multics System _ 
e Organick, Elliot I., The Multics System: An Examination of Its Structure, 
The MIT Press, Cambridge, MA (1972). 


The most basic and influential paper on historical implementations is 

e Ritchie, D. M. and Thompson, K., “The UNIX Time-Sharing System,” Bell 
System Technical Journal 57(6 Part 2) pp. 1905-1929 American Telephone 
and Telegraph Company, (July-August 1978). This is a revised version 
and describes Version 7. 

e Ritchie, D. M. and Thompson, K., “The UNIX Time-Sharing System,” Com- 
mun. ACM 177) pp. 365-375 Association for Computing Machinery, (July 
1974). This is the original paper, which describes Version 6. 
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The Version 7 manual is 
e AT&T, UNIX Time Sharing System: UNIX Programmer’s Manual, Seventh 
Edition, Bell Telephone Laboratories, Inc., Murray Hill, New Jersey (Janu- 
ary, 1979). 


Dennis Ritchie has also done several papers on the history and evolution of 
the system 

e Ritchie, Dennis, “The Evolution of the UNIX Time-sharing System,” AT&T 
Bell Laboratories Technical Journal 63(8) pp. 1577-1593 American Tele- 
phone and Telegraph Company, (October 1984). 

e Ritchie, Dennis M., “Reflections on Software Research,” Commun. ACM 
27(8) pp. 758-760 Association for Computing Machinery, (August 1984). 
ACM Turing Award Lecture. 

e Ritchie, Dennis M., “Unix: A Dialectic,” Winter 1987 USENIX Association 
Conference Proceedings, Washington, DC, pp. 29-34 USENIX Association, 
P.O. Box 2299, Berkeley, CA 94710, (21-23 January 1987). 


Important collections of papers on the system may be found in 
e BSTJ, “UNIX Time-Sharing System,” Bell System Technical Journal 57(6 
Part 2)American Telephone and Telegraph Company, (July-August 1978). 
e BLTJ, “The UNIX System,” AT&T Bell Laboratories Technical Journal 63(8 
Part 2)American Telephone and Telegraph Company, (October 1984). 


The System ITI manual is 
e AT&T, UNIX System III Programmer’s Manual, Western Electric Company, 
Inc., Greensboro, N.C. (October, 1981). 


The SVID 
e AT&T, System V Interface Definition, Issue 2, AT&T (1986). 


may be ordered from: 


AT&T Customer Information Center 
Attn: Customer Service Representative 
P.O. Box 19901 

Indianapolis, IN 46219 


(800) 432-6600 (Inside U.S.A.) 
(800) 255-1242 (Inside Canada) 
(317) 352-8557 (Outside U.S.A. and Canada) 


using the following Select Codes: 


320-011 Volume I 
320-012 Volume II 
320-013 Volume III 
307-131 all three volumes 
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The implementation of System V is described in 
e Bach, Maurice J., The Design of the UNIX Operating System, Prentice-Hall, 
Englewood Cliffs, New Jersey (1986). 


The 4.3BSD manual 
e UCB-CSRG, 4.3 Berkeley Software Distribution, Virtual VAX-11 Version, 
The Regents of the University of California, Berkeley, California (April 
1986). 


is printed by the USENIX Association, and their members may order from them: 


USENIX Association 
P.O. Box 2299 
Berkeley, CA 94710 
(415) 528-8649 


The implementation of the kernel of 4.3BSD is described in 
e Quarterman, John S., Silberschatz, Abraham, and Peterson, James L.., 
“4,.2BSD and 4.3BSD as Examples of the UNIX System,” ACM Computing 
Surveys 17(4)pp. 379-418 Association for Computing Machinery, 
(December 1985). 


e Leffler, Samuel J., McKusick, Marshall Kirk, Karels, Michael J., Quarter- 
man, John 8., and Stettner, Armando, The Design and Implementation of 
the 4.3BSD UNIX Operating System, Addison-Wesley, Reading, Mas- 
sachusetts (1988). 


B.11.3 Historical Application Programming Tutorials. A_ useful 
tutorial on programming in the C language is 
e Harbison, Samuel P. and Steele, Guy L., C: A Reference Manual, Prentice- 
Hall, Englewood Cliffs, New Jersey (1987). 


A highly regarded book, though not one for beginners, is 
e Kernighan, Brian W. and Pike, Rob, The UNIX Programming Environ- 
ment, Prentice-Hall, Inc., Englewood Cliffs, New Jersey (1984). 


One more oriented towards Berkeley systems is 
e McGilton, Henry and Morgan, Rachel, Jntroducing the UNIX System, 
McGraw-Hill (BYTE Books), New York (1983). 


and a more recent one is 
e Rochkind, Marc J., Advanced UNIX Programming, Prentice-Hall, Engle- 
wood Cliffs, New Jersey (1985). 
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For Applications Portability Look 
to IEEE’s POSIX Standard. 


4 


, IEEE Std 1003.1-1988 defines a standard operating system interface and 
,” environment based on the UNIX* Operating System documentation to pro- 

e vide for the portability of applications software at the source-code level, 
/ between computer systems from multiple vendors. 

in its present form, the standard focuses primarily on the C Language 
interface to the operating system. It complements related standards for 
computer languages, database management, and computer graphics, 
and is intended to be used by both application developers and system 
implementors. 

The IEEE POSIX specification provides a solid base for systems procure- 
ment and evaluation. Specifying POSIX conformance will allow system pur- 
chasers to productively manage their software environments and to 
achieve the benefits from applications portability. Hardware and software 
manufacturers will have a clear specification to follow in designing systems 
and applications for the open software environment. 

This standard also constitutes a major step in the industry to provide a 
comprehensive applications environment. The IEEE’s POSIX committees are 
continuing POSIX-related standards work in areas such as POSIX-based 
Open System architecture (IEEE Project 1003.0), shell and utilities (IEEE Pro- 
ject 1003.2), test methods (IEEE Project 1003.3), real time systems interfaces 
(IEEE Project 1003.4), Ada language binding for POSIX (IEEE Project 
1003.5), and systems security (IEEE Project 1003.6). 

To be placed on our mailing list for these yet-to-be-published standards, 
please send your name, address, and the project numbers that interest 
you to: The Institute of Electrical and Electronics Engineers, Inc., The Stan- 
dards Department, 445 Hoes Lane, PO Box 133], Piscataway, NJ 08855- 
1331, USA. 


> *UNIX is a registered trademark of AT&T. 
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